cavemem CLAUDE.md

cavemem — Agent Playbook

This file is the source of truth for AI coding assistants working on this repository. Follow it before generating code, tests, or documentation. If a request conflicts with this file, pause and ask.

Project identity

cavemem is a cross-agent persistent memory system for coding assistants. It captures observations from editor sessions, compresses prose using the project's deterministic caveman grammar, stores entries in a local SQLite + vector index, and exposes them to agents through a Model Context Protocol (MCP) server and a local web viewer.

The signature property of the project is that memory is stored compressed. Every write path runs text through @cavemem/compress. Every human-facing read path runs it back through @cavemem/compress#expand. Model-facing reads may keep content compressed when the caller requests it.

Non-negotiable rules

1. All persisted prose must pass through packages/compress before hitting storage. Writing raw prose to SQLite is a defect. If you add a new write path, it must use MemoryStore, which enforces this.
2. Never compress technical tokens. Code blocks, inline code, URLs, file paths, shell commands, version numbers, dates, numeric literals, and quoted identifiers are preserved byte-for-byte. The tokenizer in packages/compress/src/tokenize.ts is the single authority.
3. Round-trip tests must pass. Any change to the compressor, the lexicon, or the tokenizer requires pnpm --filter @cavemem/compress test green, including the technical-token preservation suite.
4. Progressive disclosure in MCP. search and timeline return compact results (IDs + snippets). Full observation bodies are only returned by get_observations(ids[]). Do not bloat the compact shapes.
5. Hot-path hooks are fast. Hook handlers in packages/hooks must complete under 150 ms p95. Summarization, embedding, and indexing are handed off to the worker. No network calls in hooks.
6. Privacy is enforced at the write boundary. Content inside <private>…</private> tags is stripped. Paths matching settings.excludePatterns are never read. Neither appears in logs.
7. Local by default. Default embedding provider is local (Transformers.js). Remote providers are opt-in via settings. Do not add default network calls.
8. No silent failures. Hook and worker errors are logged as structured JSON; user-visible commands surface failures with a non-zero exit code and a short message.
9. No daemon on the write path. Hooks write observations synchronously through MemoryStore.addObservation — never across a network or HTTP boundary. Hooks may detach-spawn the worker to kick off background embedding, but they must never wait on it. If the worker is down, writes still succeed; only the semantic-search side is degraded (BM25 keeps working).