mempalace/website/concepts/aaak-dialect.md

AAAK Dialect

AAAK is an experimental lossy abbreviation system designed to pack repeated entities and relationships into fewer tokens at scale. It is readable by any LLM — Claude, GPT, Gemini, Llama, Mistral — without a decoder.

::: warning Experimental AAAK is a separate compression layer, not the storage default. The 96.6% benchmark score comes from raw verbatim mode. AAAK mode currently scores 84.2% R@5 — a 12.4 point regression. We're iterating. :::

What AAAK Is

• Lossy, not lossless. Uses regex-based abbreviation, not reversible compression.
• A structured summary format. Extracts entities, topics, key sentences, emotions, and flags from plain text.
• Readable by any LLM. No decoder needed — models read it naturally.
• Designed for scale. Saves tokens when the same entities appear hundreds of times.

What AAAK Is Not

• Not lossless compression. The original text cannot be reconstructed.
• Not efficient at small scale. Short text already tokenizes efficiently — AAAK overhead costs more than it saves.
• Not the default storage format. MemPalace stores raw verbatim text in ChromaDB.

Format

Header:   FILE_NUM|PRIMARY_ENTITY|DATE|TITLE
Zettel:   ZID:ENTITIES|topic_keywords|"key_quote"|WEIGHT|EMOTIONS|FLAGS
Tunnel:   T:ZID<->ZID|label
Arc:      ARC:emotion->emotion->emotion

Entity Codes

Three-letter uppercase codes: ALC=Alice, KAI=Kai, MAX=Max.

Emotion Codes

Code	Meaning	Code	Meaning
vul	vulnerability	joy	joy
fear	fear	trust	trust
grief	grief	wonder	wonder
rage	rage	love	love
hope	hope	despair	despair
peace	peace	humor	humor
tender	tenderness	raw	raw honesty
doubt	self-doubt	relief	relief
anx	anxiety	exhaust	exhaustion

Flags

Flag	Meaning
ORIGIN	Origin moment (birth of something)
CORE	Core belief or identity pillar
SENSITIVE	Handle with absolute care
PIVOT	Emotional turning point
GENESIS	Led directly to something existing
DECISION	Explicit decision or choice
TECHNICAL	Technical architecture detail

Example

Input:

We decided to use GraphQL instead of REST because the frontend team needs
flexible queries. Kai recommended it after researching both options. The team
was excited about the schema-first approach.

AAAK output:

0:KAI|graphql_rest_decided|"decided to use GraphQL instead of REST"|determ+excite|DECISION+TECHNICAL

Usage

Compress drawers

# Preview compression
mempalace compress --wing myapp --dry-run

# Compress and store
mempalace compress --wing myapp

With entity config

mempalace compress --wing myapp --config entities.json

Entity config format:

{
  "entities": {"Alice": "ALC", "Bob": "BOB"},
  "skip_names": ["Gandalf", "Sherlock"]
}

Python API

from mempalace.dialect import Dialect

# Basic compression
dialect = Dialect()
compressed = dialect.compress("We decided to use GraphQL...")

# With entity mappings
dialect = Dialect(entities={"Alice": "ALC", "Kai": "KAI"})
compressed = dialect.compress(text, metadata={"wing": "myapp", "room": "arch"})

# From config file
dialect = Dialect.from_config("entities.json")

When to Use AAAK

AAAK is most useful when:

• You have many repeated entities across thousands of sessions
• You need to compress context for local models with small windows
• You want structured summaries pointing back to verbatim drawers

For most users, raw verbatim mode is the better default.