CTX: I gave Claude Code a memory that actually works

#opensource

The problem

Claude Code resets every session. There is no built-in memory. You open a new terminal, start coding, and the model has no idea what you decided yesterday, what architecture you settled on, or which files matter. You explain it again. Every time.

I spent three months building something to fix this.

What CTX does

CTX hooks into Claude Code's UserPromptSubmit event. Before every prompt, three things happen — in under 1ms:

G1 — Decision memory
Parses your git log and surfaces the most relevant past decisions. "Why did we switch to BM25?" "What was the reasoning behind this architecture?" CTX pulls those commit messages and injects them before you even ask.

G2 — Code and doc search
BM25 search across your entire codebase and markdown docs. When you ask about a function, the right files are already in context. No more "I can't find that file" hallucinations.

CM — Chat memory vault
A local SQLite database of past conversations, hybrid-searched (BM25 + optional vector). The things you explained once, you should only have to explain once.

The numbers

I ran rigorous benchmarks — not synthetic toy tests.

Memory recall (MAB, N=50)

System	Recall	Wilson CI 95%
None (baseline)	0.00	[0.00, 0.07]
CTX	0.40	[0.28, 0.54]
CTX v2	0.58	[0.44, 0.71]
CTX v3	0.88	[0.762, 0.944]

CTX v3 vs baseline: McNemar p < 0.001. Statistically significant.

Real-world telemetry (10,000+ turns)

Overall utility rate: 39.6% (items injected that Claude actually cited)
CM block: 52.6% utility rate (highest — chat memory is the most cited)
G1 block: 39.6%
G2 docs: 27.8%

A 42 percentage point gap between KEYWORD (16%) and SEMANTIC (42%) queries confirms retrieval method selection matters — and CTX routes them differently.

How it installs

Option A — Native plugin (recommended, one step):

/plugin install ctx@jaytoone

Claude Code handles everything — venv, daemons, hooks. No terminal needed.

Option B — PyPI:

pip install ctx-retriever && ctx-install

Copies hooks to ~/.claude/hooks/ and patches settings.json atomically. Validated in clean Docker (ubuntu:22.04).

Latest: v0.3.13 — vec-daemon isolated venv (no numpy/ABI conflicts). BGE reranker opt-in: CTX_BGE_ENABLE=1.

What it does not do

No cloud sync. Everything stays local.
No LLM calls. Pure BM25 + SQLite.
No mandatory telemetry. Opt-in only.
Does not replace Claude's context window — it fills it intelligently before you ask.