Skill: twacqwq/turboquant (version 0.1.0)

--- name: turboquant version: 0.1.0 description: > Compress conversation context into a TurboQuant vector store inside OpenClaw memory, then retrieve the most relevant entries on demand to stay within token budgets. metadata: { "openclaw": { "requires": { "bins": ["uv"] }, "emoji": "⚡", "homepage": "https://github.com/openclaw/openclaw-turboquant" } } --- # 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.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)