Appendix C: AAAK Dialect Complete Reference

This appendix consolidates the AAAK_SPEC constant from mcp_server.py and the complete encoding tables from dialect.py, providing a searchable reference for the AAAK dialect. Source baseline: the current MemPalace source snapshot discussed in this book.

Overview

AAAK is a compressed shorthand format designed for AI agents. It is not meant for human reading -- it is meant for LLMs. Any model that can read English (Claude, GPT, Gemini, Llama, Mistral) can understand AAAK directly, without a decoder or fine-tuning.

Format Structure

Line Types

Field Separators

• Pipe | separates different fields within the same line
• Arrow → denotes causal or transformational relationships
• Stars ★ to ★★★★★ indicate importance (1--5 scale)

Entity Encoding

Entity names are encoded as the first three letters in uppercase:

Source location: dialect.py:367-379 (encode_entity method)

Emotion Encoding Table

AAAK uses standardized short codes to represent emotional states.

Core Emotion Codes

Source location: dialect.py:47-88 (EMOTION_CODES dictionary)

Shorthand Markers in the MCP Server

The AAAK_SPEC in mcp_server.py uses *marker* format to annotate emotional context:

Emotion Signal Detection

dialect.py automatically detects emotions in text via keyword matching:

Source location: dialect.py:91-114 (_EMOTION_SIGNALS dictionary)

Semantic Flags

Flags mark the type of factual assertion, aiding retrieval and classification.

Source location: dialect.py:117-152 (_FLAG_SIGNALS dictionary)

Palace Structure Identifiers

Full Example

Original English (~70 tokens)

Priya manages the Driftwood team: Kai (backend, 3 years), Soren (frontend),
Maya (infrastructure), and Leo (junior, started last month). They're building
a SaaS analytics platform. Current sprint: auth migration to Clerk.
Kai recommended Clerk over Auth0 based on pricing and DX.

AAAK Encoding (~35 tokens)

TEAM: PRI(lead) | KAI(backend,3yr) SOR(frontend) MAY(infra) LEO(junior,new)
PROJ: DRIFTWOOD(saas.analytics) | SPRINT: auth.migration→clerk
DECISION: KAI.rec:clerk>auth0(pricing+dx) | ★★★★

Factual Assertion Verification

For this short structured example, all 13/13 factual assertions are preserved. Compression ratio ~2x (this example is short and information-dense).

AAAK_SPEC in the MCP Server

The following is the complete specification passed to the AI via the mempalace_status tool, found at mcp_server.py:102-119:

AAAK is a compressed memory dialect that MemPalace uses for efficient storage.
It is designed to be readable by both humans and LLMs without decoding.

FORMAT:
  ENTITIES: 3-letter uppercase codes. ALC=Alice, JOR=Jordan, RIL=Riley, MAX=Max, BEN=Ben.
  EMOTIONS: *action markers* before/during text. *warm*=joy, *fierce*=determined,
            *raw*=vulnerable, *bloom*=tenderness.
  STRUCTURE: Pipe-separated fields. FAM: family | PROJ: projects | ⚠: warnings/reminders.
  DATES: ISO format (2026-03-31). COUNTS: Nx = N mentions (e.g., 570x).
  IMPORTANCE: ★ to ★★★★★ (1-5 scale).
  HALLS: hall_facts, hall_events, hall_discoveries, hall_preferences, hall_advice.
  WINGS: wing_user, wing_agent, wing_team, wing_code, wing_myproject,
         wing_hardware, wing_ue5, wing_ai_research.
  ROOMS: Hyphenated slugs representing named ideas (e.g., chromadb-setup, gpu-pricing).

EXAMPLE:
  FAM: ALC→♡JOR | 2D(kids): RIL(18,sports) MAX(11,chess+swimming) | BEN(contributor)

Read AAAK naturally — expand codes mentally, treat *markers* as emotional context.
When WRITING AAAK: use entity codes, mark emotions, keep structure tight.

Under the current protocol, the AI receives this specification when it explicitly calls mempalace_status and a palace already exists. This is not an out-of-band automatic injection path.

Compression Pipeline

The compress() method in dialect.py performs five-stage processing:

graph TD
    A[Raw Text] --> B["1. Entity Detection<br/>name[:3].upper()"]
    B --> C["2. Topic Extraction<br/>Remove stopwords + frequency sort"]
    C --> D["3. Key Sentence Selection<br/>_extract_key_sentence()"]
    D --> E["4. Emotion/Flag Detection<br/>Keyword → code mapping"]
    E --> F["5. AAAK Assembly<br/>Pipe-separated + header line"]

For the current dialect.compress() plain-text path, a more accurate description is that all five stages contain heuristic selection, not only Stage 3. Entities, topics, emotions, and flags are all detected and truncated; key_sentence is simply the most obvious selection step. The current pipeline is closer to a high-compression index generator than to a strictly lossless encoder.

The "lossless AAAK" discussed elsewhere in the README and book is best understood as a design goal: truly preserving fact-by-fact structure would require a stronger alignment between the compressor and the original text than the current heuristic plain-text pipeline provides.

Source location: dialect.py:539-602 (compress method)

AAAK Dialect Completeness Assessment

Implemented Capabilities

Missing Critical Capabilities

As a "language," AAAK lacks key linguistic infrastructure:

Core Qualitative Judgment

AAAK is not a language — it is a compression function.

A true language requires three elements:

1. Syntax — what constitutes a valid AAAK string. AAAK partially has this (pipe separation, header line format), but without formal definition.
2. Semantics — the meaning definition of each symbol. AAAK has this (emotion code table has clear semantics).
3. Roundtrip capability — information is preserved after encode→decode. AAAK completely lacks this.

compress() is a one-way function — it compresses text into AAAK format, but there is no corresponding decompress() to verify whether information was actually preserved. The README's "lossless" claim relies on "LLMs can read AAAK" — this delegates verification responsibility to the model's reasoning capability rather than the format's own reversibility guarantee.

In Fairness

1. The design intuition is correct — "extremely abbreviated English, let the LLM be the decoder" genuinely works, because LLM language understanding can fill in omitted information.
2. Engineering-sufficient — as a Closet-layer index (not the sole storage), AAAK does not need strict losslessness — Drawers preserve the originals.
3. Cross-model readability is real — any English-capable model can indeed understand KAI(backend,3yr); this property does not depend on AAAK's formal completeness.
4. 950 lines of code achieved usability — for a v3.0.0 project, this implementation sufficiently supports the benchmark results.

Overall Ratings

The most honest positioning: AAAK is an AI-oriented shorthand index format that enables any LLM to quickly understand context summaries through extremely abbreviated English, while relying on the Drawer layer to preserve complete original text as a safety net. Its core value lies not in "lossless compression" but in "cross-model-readable efficient indexing."