Captures decisions, bug fixes, and learnings from every Claude Code and Codex session — and injects them back on the next one, in either agent. No cloud. No config. Just memory.
npm install -g somtum
somtum init --all # Claude Code: hooks + MCP server in this project
somtum init --agent codex # Codex: hooks + MCP server in this projectThat's it. Every session from here will be captured and remembered, whichever agent you use.
After a debugging session, Somtum extracts observations like these and stores them locally:
[
{
"kind": "bugfix",
"title": "JWT refresh loop — Unix timestamps are seconds, not ms",
"body": "Checked token.exp < Date.now() instead of token.exp < Date.now() / 1000."
},
{
"kind": "decision",
"title": "Use pnpm workspaces — npm hoisting breaks shared types",
"body": "Switched from npm because hoisting put shared type packages in the wrong scope."
}
]Next session, when you ask "why are we using pnpm?" the agent already knows. No re-explanation needed.
Run somtum doctor after install to verify your setup:
✓ config strategy=bm25, k=8
✓ db_open WAL mode, foreign_keys ON
✓ extraction_backend claude-cli (auto)
✓ hooks_installed somtum hooks found in .claude/settings.json, .codex/hooks.json
✓ embeddings disabled (set retrieval.embeddings.enabled=true to enable)Hybrid strategy requires embeddings
If doctor reports strategy=hybrid but embeddings: disabled, somtum silently falls back to BM25 while paying hybrid overhead. Fix it with one command:
somtum config set retrieval.strategy bm25 # match what's actually runningOr enable full hybrid (requires ANTHROPIC_API_KEY):
somtum config set retrieval.embeddings.enabled trueSee Configuration → Retrieval strategy for details.
somtum stats shows whether memory is paying for itself:
| Metric | Good sign | What to check |
|---|---|---|
breakeven ≥ 1.5x | Saving more than you spend | Expected after ~20+ memories |
cache hits > 0 | Repeated queries are cached | Confirm cache.enabled = true |
retrieval calls accumulating | Memories being actively recalled | Check injection.enabled = true |
A fresh project (< 10 memories) will often show a net negative — this is normal and improves with use.