ContextWeave is a hook kit for Claude Code that persists prompt, tool, and final traces into Beads and rehydrates working context after compaction. It gives long-running coding agents a deterministic memory layer without running a separate service.
Search terms: Claude Code hooks, Beads memory, agent context persistence, AI coding assistant memory, prompt trace logging, compaction rehydration.
- Persist prompt trees into Beads through the
bdCLI instead of asking the model to maintain its own memory files. - Rehydrate the agent with
bd prime --full, recent prompt/final summaries, and open work after session start or compaction. - Fire trace hooks asynchronously so they never add latency to tool calls.
- Expose
search-beads— a semantic retrieval tool backed by a local ONNX model (all-MiniLM-L6-v2) that lets the model search history via its native Bash tool without MCP. - Stay operationally simple: plain Node scripts, Claude Code hook bindings, a
.beadsworkspace, and a local model cache.
# 1. Initialize Beads in stealth mode (per project — no git tracking)
cd /path/to/project
BEADS_DIR="$(pwd)/.beads" bd init --quiet --stealth
echo ".beads/" >> .gitignore
# 2. Clone and install ContextWeave, then delete the repo — not needed after setup
git clone https://github.com/your-org/ContextWeave
cd ContextWeave
node install.js
cd .. && rm -rf ContextWeaveThe installer copies everything to ~/.contextweave/, links search-beads onto your PATH, and prints the exact hook config block to paste into ~/.claude/settings.json.
# 3. Verify everything is wired correctly
node ~/.contextweave/doctor.js# 4. Inspect your first Beads trace after running a prompt
bd list --all --sort created --reverse --limit 5See setup.md for the full setup guide and setup-claude.md for hook configuration details.
Claude Code
│
├─ SessionStart → 1-context-start.js → inject bd prime + open issues
├─ UserPromptSubmit → 2-context-before-agent.js → rehydrate / inject reminder
├─ PreToolUse (async) → 7-context-after-tool.js → trace tool call
├─ PostToolUse (async) → 7-context-after-tool.js → trace tool result
├─ PreCompact → 3-context-precompress.js → write rehydrate marker
├─ Stop (async) → 6-context-after-agent.js → trace final response
└─ SessionEnd (async) → 5-context-end.js → cleanup
The hooks do two jobs: inject the right working context back into the model, and persist a structured prompt tree you can inspect later with Beads.
- Setup Overview — prerequisites, stealth mode, Dolt backend options.
- Claude Code Setup — hook config, stealth init, verification.
- Architecture — hook flow, persistence model, compaction behavior.
- Trace Model — trace issue types, helper files, environment variables.
- ADR 001 — why Beads + hooks is the persistence model.
- ADR 002 — why rehydration is summary- and dependency-aware.
- ADR 003 — why deterministic hooks sit outside the model loop.
Evaluated on LongMemEval (ICLR 2025) — 400 questions across six long-term memory abilities, using Claude Sonnet 4.6 via AWS Bedrock.
| Condition | Accuracy | Avg Input Tokens |
|---|---|---|
| Baseline — full conversation context | 59.5% | 115,660 |
| ContextWeave — bead retrieval | 68.2% | 102,791 |
+8.7 percentage points accuracy at 11% lower token cost.
| Question Type | Baseline | ContextWeave | Delta |
|---|---|---|---|
| single-session-user | 80% | 94% | +14pp |
| single-session-assistant | 93% | 93% | — |
| single-session-preference | 17% | 57% | +40pp |
| multi-session | 57% | 65% | +8pp |
| temporal-reasoning | 20% | 34% | +14pp |
| knowledge-update | 78% | 72% | −6pp |
The biggest gains are on preference recall (+40pp) and temporal reasoning (+14pp). The benchmark runner lives in benchmarks/longmemeval-ab/.
- Plain CommonJS scripts, no build step.
bdmust be onPATH.SessionStartmatcher is""(empty) — fires on startup, resume, clear, and compact.- Trace hooks (
PreToolUse,PostToolUse,Stop,SessionEnd) run withasync: true— non-blocking. PreCompactoutput becomescustomInstructionsfor the compaction LLM, guiding it to preserve Beads state.- Rehydration uses a
.needs_rehydratemarker written by3-context-precompress.jsand consumed by2-context-before-agent.js.