ClawMem AGENTS.md

ClawMem — Agent Quick Reference

On-device retrieval-augmented memory for Claude Code, OpenClaw, and Hermes agents. Hooks auto-inject context (~90%); MCP tools cover targeted recall (~10%). TypeScript on Bun, MIT.

This file is the lean root SSOT — agent-facing essentials only. Deep reference lives in docs/ (linked throughout, indexed at the bottom). CLAUDE.md is an @AGENTS.md import; SKILL.md is the portable on-demand operating reference.

---

Inference at a glance

Three services — embedding, LLM (query expansion / intent / A-MEM), reranker. Default: all three as llama-server with an in-process node-llama-cpp fallback that auto-downloads on first use (works with no GPU). The bin/clawmem wrapper points at localhost:8088/8089/8090. Always run via bin/clawmem — it sets the endpoints.

Choose a stack:

• native (default) — EmbeddingGemma-300M + qmd-query-expansion-1.7B + qwen3-reranker-0.6B · ~4 GB or in-process · permissive, commercial OK · zero-config.
• z / SOTA — zembed-1 + qmd-query-expansion-1.7B + zerank-2 seq-cls sidecar · ~16 GB · CC-BY-NC-4.0, non-commercial only · best recall.
• cloud embedding — Jina/OpenAI/Voyage/Cohere · embedding only (LLM + reranker stay local) · no local GPU needed.

Landmines:

• The zerank-2 GGUF is inert — llama.cpp drops the score head → ranking silently collapses to RRF. Use the seq-cls sidecar; verify with clawmem rerank-health (liveness ≠ correctness).
• A squatted port answers HTTP but serves nothing — an unrelated service on 8088/8089 used to disable enrichment silently forever. Since v0.37.0 persistent HTTP errors trip the 60s cooldown (405/501 instantly, other non-2xx after 3 consecutive) so the fallback engages, and clawmem doctor shape-probes CLAWMEM_LLM_URL with a real completion.
• -ub must equal -b for embedding/reranking (non-causal attention) or llama-server asserts.
• Changing embedding dimensions → clawmem embed --force (full re-embed).
• Changing the embedding model (even at the same dimension) → clawmem embed --force; querying otherwise now throws VecReadModelMismatchError instead of serving cosine-meaningless results (v0.18.0).
• CLAWMEM_NO_LOCAL_MODELS=true to fail fast instead of silent CPU fallback.