TurboQuant Context Compression Skill#

Maintains a compressed vector store in OpenClaw's memory directory ( ~/.openclaw/memory/turboquant-$OPENCLAW_SESSION_ID) and provides three lifecycle commands: ingest → assemble → compact.

Store path convention#

The store path is automatically derived from the session:

bash

STORE=~/.openclaw/memory/turboquant-$OPENCLAW_SESSION_ID

All commands default to this path when --store is omitted.

---

Phase A — Ingest (after each turn)#

After every message, save the embedding vector of that message text to the store. Embeddings must be pre-computed and saved as a .npy file by the caller.

bash

# Add one message to the store
uv run openclaw-turboquant ingest \
  --id "turn_$TURN_NUMBER" \
  --text "Full message text goes here" \
  --embedding /tmp/turn_embedding.npy

# Output:
# {"action":"ingest","entry_id":"turn_5","store_size":5,"store_path":"...","ok":true}

--store, --dim, --bit-width are inferred automatically on subsequent calls. Set --dim only when creating a store for the first time.

---

Phase B — Assemble (before building the prompt)#

Retrieve the most relevant past entries that fit within the token budget.

bash

uv run openclaw-turboquant assemble \
  --query /tmp/current_query.npy \
  --token-budget 4096

# Output (one JSON object per line, sorted by relevance):
# {"role":"context","content":"...","entry_id":"turn_3","score":0.912}
# {"role":"context","content":"...","entry_id":"turn_1","score":0.743}

Include the returned content fields as context messages in the system prompt.

---

Phase C — Compact (when the context window is filling up)#

Remove the least relevant entries when the store grows too large. Trigger this when store_size exceeds a threshold (e.g., 50).

bash

uv run openclaw-turboquant compact \
  --query /tmp/current_query.npy \
  --keep-ratio 0.5

# Output:
# {"action":"compact","before":50,"after":25,"removed":25,"ok":true}

---

Inspect the store#

bash

uv run openclaw-turboquant store-info

# Output:
# {"path":"/...","size":25,"dim":1536,"bit_width":4,"memory_bytes":12288,"memory_kb":12.0}

---

Low-level commands (batch file operations)#

bash

# Compress a batch of embeddings from a .npy file
uv run openclaw-turboquant compress \
  --input embeddings.npy --output compressed.npz --bit-width 4

# Retrieve top-k from a compressed file index
uv run openclaw-turboquant retrieve \
  --query query.npy --index compressed.npz --top-k 5

# Benchmark distortion quality
uv run openclaw-turboquant benchmark --dim 128 --bit-width 4 --n-vectors 1000

---

Notes#

• Embeddings are not generated by this skill. The caller must produce .npy vectors using any embedding model (e.g., text-embedding-3-small).
• The store persists across turns inside ~/.openclaw/memory/ so context survives session restarts.
• bit-width 4 is the recommended default: ~6× compression with negligible quality loss.
• Use prod mode (default) for retrieval; it provides unbiased inner-product estimation.
• Requires uv on $PATH and uv sync run once in the project directory.