"Cellar door." Tolkien called it the most beautiful phrase in English. You store things in a cellar — facts, memories, the stuff agents need to remember. The name is the spec.
Cellar Door is a typed, cross-agent shared-memory subsystem for local AI agents.
It gives CAST agents a common fact store with provenance, temporal supersession,
and model-agnostic injection — so a Claude-routed code-writer and an
Ollama-routed code-reviewer can share what they know without being told the same
things twice. Storage is SQLite inside the existing ~/.claude/cast.db.
No daemon, no port, no cloud.
- Phase 0: scaffold complete
- Phase 1: schema migration + FTS5 (live)
- Phase 2: UserPromptSubmit injection hook (live)
- Phase 3: SubagentStop write-back hook (live)
- Phase 4: supersession + temporal queries + cast-memory CLI (live)
- Phase 5: CCR/Ollama parity verified (live)
bash install.sh
# With Phase 2 hook wiring:
bash install.sh --yesPhase 2 adds a UserPromptSubmit hook that retrieves relevant memories from
cast.db and injects them as additionalContext before every Claude/Ollama prompt.
Per session:
CAST_COG_ENABLED=1 claudeAlways-on (add to ~/.zshrc):
export CAST_COG_ENABLED=1On each user prompt, the hook calls cast-memory-router.py --fts-only to retrieve
the top-5 most relevant memories from the shared memory pool. Retrieved memories are
injected into additionalContext in this format:
[cellar-door] retrieved 3 memories
[mem] type=feedback name=editorial_pullback score=0.78 content="lean toward complete shippable choices"
[mem] type=user name=collaboration_style score=0.62 content="values teammate dynamic over tool dynamic"
[mem] type=project name=aether score=0.51 content="commercial dev terminal, 26-week roadmap"
Content is truncated at 120 characters.
| Variable | Default | Description |
|---|---|---|
CAST_COG_TOP_K |
5 |
Max memories to retrieve per prompt |
CAST_COG_AGENT |
shared |
Memory pool to query |
CAST_COG_TYPE_FILTER |
(none) | Filter by type: user, feedback, project, reference |
CAST_COG_MIN_SCORE |
0.3 |
Minimum relevance score threshold |
The hook fires in the main Claude Code session before routing. Both Anthropic-backed and Ollama-backed (CCR) model paths receive identical injected context — no extra configuration needed.
Target: <100ms p95. FTS-only retrieval (no Ollama embed call) typically runs in
10–30ms. The hook self-monitors and logs a warning to stderr if latency exceeds 100ms.
Hook never blocks the prompt — any error path exits 0 with empty additionalContext.
Cellar Door's memory hooks are model-agnostic by design. The inject and write-back
hooks talk to cast.db — not to the LLM. Whether a session runs via claude (Anthropic)
or ccr (Ollama/deepseek-coder), the same hook fires on UserPromptSubmit and
SubagentStop, reading from and writing to the same fact store.
Empirically verified (2026-04-28): BATS regression tests in tests/test_parity_inject.bats
and tests/test_parity_writeback.bats assert identical retrieve and write-back outcomes
for both backends against a fixed fact corpus.
To run parity tests:
bats tests/test_parity_inject.bats tests/test_parity_writeback.batsSee ~/.claude/plans/cast-shared-cognition-roadmap.md for the full phased build plan,
schema decisions, and injection-hook design.
MIT — see LICENSE.