EpochDB Long-Term Memory

EpochDB Long-Term Memory — Claude Code Plugin

Give Claude Code an automatic, local, offline long-term memory.

• 🧠 Recall — on every prompt, the most relevant facts from your past sessions are semantically retrieved and injected as context.
• 💾 Auto-save — at the end of every turn, the exchange is stored back to a local EpochDB instance.
• 🔌 Portable — no hard-coded paths, no external services. Self-bootstraps a private virtualenv on first run. Works on Linux, macOS, and Windows.

Install

From a marketplace (recommended)

/plugin marketplace add jersobh/epochdb-memory-plugin
/plugin install epochdb-memory@epochdb-memory

On first session the plugin creates its own .venv and installs EpochDB in the background. Memory recall lights up automatically once that finishes (a minute or two the first time). Nothing else is required.

Manual / offline

git clone https://github.com/jersobh/epochdb-memory-plugin
cd epochdb-memory-plugin
./setup.sh            # creates .venv and installs deps
claude --plugin-dir "$PWD"

Commands

• /memory-stats — show counts, storage path, and retrieval mode.
• /memory-search <query> — semantically search stored memories.

How it works

Hook	Script	What it does
SessionStart	hooks/setup_epochdb.py	Ensures the venv + EpochDB exist (background install).
UserPromptSubmit	hooks/epoch_memory_hook.py	Retrieves top-k relevant memories, injects them via additionalContext.
Stop	hooks/epoch_save_hook.py	Parses the transcript and saves the finished turn.

Hooks ship with a #!/usr/bin/env python3 shebang and re-exec themselves into the plugin's private venv at runtime — so they run correctly regardless of the machine, the user, or where the plugin is installed. If EpochDB isn't ready yet, every hook degrades to a harmless no-op.

Configuration

Env var	Default	Meaning
EPOCHDB_STORAGE_DIR	~/.epochdb	Where memories are stored.

zsh users: pip install epochdb[embeddings] fails with zsh: no matches found because zsh expands the [...]. Quote it: pip install "epochdb[embeddings]". The embeddings extra does exist; this is purely shell globbing. setup.sh, requirements.txt, and the SessionStart hook all already quote it, so the automatic path is unaffected.

Embedding modes

• Semantic (default): installs epochdb[embeddings] (sentence-transformers
  • torch) and uses all-MiniLM-L6-v2. Fully offline after the first run.
• Lightweight fallback: if that wheel can't be installed for your Python, the plugin automatically falls back to base epochdb (entity/keyword retrieval). Memory still works, with weaker recall.

Tip: to avoid the large CUDA torch download, pre-install the CPU build into the plugin venv before first use: .venv/bin/pip install torch --index-url https://download.pytorch.org/whl/cpu

Token savings — what to actually expect

Run the reproducible benchmark yourself:

.venv/bin/python benchmarks/benchmark.py

It seeds a labeled project history, then measures retrieval accuracy, gating, and token economics against a real EpochDB store. Measured results:

Metric	Result
Retrieval accuracy (hit@1 / hit@3)	88% / 100%
MRR	0.92
Irrelevant prompts that inject nothing (gating)	3/3
Avg context injected per recall	~30–300 tokens (bounded by top-k)

Typical savings: ~85–98% less carried cross-session context when the realistic alternative is reloading the prior conversation (i.e. what claude --resume / --continue do — they reload the entire prior transcript, resent every turn). The plugin recalls a bounded top-k snippet only when it's relevant, so it scales: the longer the history you'd otherwise reload, the larger the reduction.

Read this honestly:

• vs. a curated CLAUDE.md or good compaction → savings ≈ 0. There the value is recall quality, not tokens.
• It only reduces INPUT context. Output tokens (the expensive part) are unchanged.
• Prompt caching makes the reload baseline cheaper than raw token counts imply, so realized dollar savings are smaller than the percentages.
• Relevance gating (EPOCHDB_MIN_SCORE, default 0.30) ensures unrelated prompts inject nothing, so the plugin doesn't tax every turn.

Net: it's a strong win when you'd otherwise reload/re-paste prior sessions, and roughly neutral (a quality feature, not a cost one) if you already keep a tight CLAUDE.md.

License

MIT © Jefferson A. (jersobh)