Deprecated. Claude Code now ships native auto memory that covers the core use case. See Claude Code Memory Documentation. This project is no longer maintained.
Deterministic State Recovery for AI Coding Agents
Sunset. Claude Code's built-in auto memory now provides per-project persistent memory, automatic context saving, and session-start loading — the core loop Momento was built for. Use Claude's native memory going forward.
Momento validated the concept: structured knowledge types, deterministic restore, cross-project context, and work summaries. The 80% use case is now native.
AI coding agents forget. Every /clear, context overflow, or new session wipes the slate. But that's just the obvious part.
The deeper problem is knowledge drift. You make decisions, hit gotchas, learn patterns — and none of it sticks anywhere durable. Your CLAUDE.md goes stale after week one. Your agent operates on partial knowledge even when you've told it everything before. And when your manager asks "what did you ship this week?" you're digging through git logs and Slack threads trying to reconstruct what happened.
The memory gap isn't just the agent's problem. It's yours too.
Momento is a local memory layer that captures, preserves, and resurfaces the knowledge generated during development:
- Context recovery — restores your agent's working state in under 2 seconds after any context reset. Decisions, gotchas, tasks in progress, and what comes next.
- Knowledge capture — decisions, gotchas, and patterns are logged as durable entries that persist across sessions, branches, and projects.
- CLAUDE.md audit — detects drift between what Momento knows and what your agent instruction file says. Surfaces gaps, flags stale references, optionally patches the file.
- Work summaries — generates daily/weekly reports from the same knowledge base. Standups, manager updates, team syncs — all from one SQLite file.
No cloud. No external dependencies. No magic.
After a context reset, the agent calls retrieve_context(). Momento returns structured directives -- not chat history, not raw logs, but distilled intent:
retrieve_context(include_session_state=true)
## Active Task
[session_state | server | feature/billing-rewrite | 10m ago]
Migrating AuthService to async/await. AuthService.swift and
AuthViewModel.swift complete. ProfileService and PaymentService
remain. Hit race condition in TokenManager -- resolved with actor
isolation.
## Project Knowledge
### Auth Token Refresh [gotcha | server | 3d ago]
- Always isolate TokenManager in an actor
- Race condition occurs if refresh overlaps with logout
- Validate refresh token before mutation
### Keychain Storage [decision | ios | 1d ago]
- Chose Keychain over UserDefaults -- UserDefaults is not encrypted
- Wrapped in KeychainManager actor for thread safetyThe agent picks up where it left off. You didn't re-explain anything.
The knowledge your agent saves during work — decisions, gotchas, session checkpoints — does double duty. Context for the agent, accountability for you.
momento snippet # Today's work
momento snippet --yesterday # Yesterday (standup prep)
momento snippet --week # Weekly summary
momento snippet --format standup # Standup format
momento snippet --format slack # Slack-friendly markdown
momento snippet --format json # Machine-readableExample daily snippet:
# Monday, Feb 23 2026 — momento
### Accomplished
- Snippets v0.2 implementation complete. 59 tests across 10 files,
snippet.py core module, CLI command, MCP tool. 410 tests passing.
- Checkpoint enforcement hooks working. Stop hook blocks session end
if no checkpoint in 30+ min. SessionStart hooks remind on resume.
- Added pre-push hook (tests + 95% coverage gate). 432 tests, 98% coverage.
### Decisions Made
- Checkpoint enforcement via hooks, not behavioral instructions.
CLAUDE.md instructions were ignored during heavy implementation.
### Still In Progress
- Discovered/Blockers sections noisy from ingested error logs.
May want to filter or limit in a future pass.Also available via MCP: generate_snippet(range="today", format="markdown").
CLAUDE.md files go stale. You accumulate weeks of decisions, gotchas, and patterns in Momento but never update CLAUDE.md. The agent reads CLAUDE.md every session but only calls Momento when instructed. Silent drift.
momento audit-claude-md compares durable Momento entries against your CLAUDE.md, reports gaps both directions, checks global adapter health, and optionally patches the file.
momento audit-claude-md # report only
momento audit-claude-md --fix # auto-patch CLAUDE.md
momento audit-claude-md --dry-run # preview changesExample output:
MISSING FROM CLAUDE.md — Momento knows, CLAUDE.md doesn't
────────────────────────────────────────────────────
Gotchas (2 not mentioned):
⚠ BM25 retrieval falls back to vector-only above 20k vectors.
(logged 12d ago · tags: bm25, retrieval)
Decisions (1 not mentioned):
📌 Switched from OpenAI embeddings to all-MiniLM-L6-v2.
(logged 11d ago · tags: embeddings, cost)
SUMMARY
────────────────────────────────────────────────────
CLAUDE.md coverage: 58% of durable Momento knowledge
Run `momento audit-claude-md --fix` to append missing entries.
--fix backs up to .bak, appends entries under matching section headers, and never touches ~/.claude/CLAUDE.md (prints suggestion instead).
- Deterministic 5-tier restore -- same inputs always produce identical output, no probabilistic scoring
- SQLite + FTS5 -- zero external dependencies, single file, BM25 keyword search built in
- MCP integration -- three tools (
retrieve_context,log_knowledge,generate_snippet), works with any MCP-compatible agent - CLAUDE.md audit -- detect drift between Momento knowledge and your agent instruction file
- 13-command CLI -- full control over your knowledge base from the terminal
- Work summaries (Snippets) -- generate daily/weekly summaries in markdown, standup, slack, or JSON
- Checkpoint enforcement -- hooks block session end if no checkpoint in 30+ min, auto-remind on resume
- Cross-agent continuity -- Claude Code saves, Codex restores (or any combination)
- Surface-aware ranking -- working in
/server? Server entries rank first automatically - Branch-aware preference -- entries from your current branch are preferred, never filtered
- Session state decay -- temporary checkpoints expire; durable knowledge persists forever
pipx install .
momento statusFor full setup including MCP server registration and agent adapters:
./setup.sh- Python 3.11+
- pipx
- Runtime:
mcp>=1.0
| Command | Description |
|---|---|
momento status |
Project health: entry counts, DB size, last checkpoint age |
momento last |
Show the most recent entry |
momento save "<msg>" |
Quick session checkpoint (auto-detects project, branch, surface) |
momento log "<msg>" --type <type> |
Log any entry with explicit type control |
momento undo |
Delete the most recent entry (with confirmation) |
momento inspect |
Browse the knowledge base with filters |
momento prune |
Delete entries by ID, filter, or auto-prune |
momento search "<query>" |
Full-text keyword search (FTS5 BM25) |
momento snippet |
Work summary (daily/weekly, markdown/standup/slack/json) |
momento ingest |
Import from Claude Code session logs |
momento check-stale |
Checkpoint freshness check (used by hooks) |
momento audit-claude-md |
Audit CLAUDE.md against Momento knowledge |
momento debug-restore |
Show restore tier breakdown for debugging |
See docs/reference.md for full CLI reference with all flags and examples.
Momento exposes three MCP tools. The server is stateless -- each call auto-resolves project, branch, and surface from the working directory.
| Tool | Purpose |
|---|---|
retrieve_context |
Restore mode (empty query) or FTS5 search mode (with query) |
log_knowledge |
Store a knowledge entry with type, content, and tags |
generate_snippet |
Work summary for a date range in any format |
Setup is handled by ./setup.sh, which registers the MCP server, agent adapters, and checkpoint enforcement hooks.
See docs/reference.md for MCP setup details and tool schemas.
When an agent loses context, Momento runs a deterministic 5-tier state reconstruction. Same inputs always produce identical output.
| Tier | Type | Quota | Window | Purpose |
|---|---|---|---|---|
| 1 | session_state |
4 surface + 2 other | 48 hours | What was I just working on? |
| 2 | plan |
2 | All time | What's the roadmap? |
| 3 | decision |
3 | All time | What did we decide and why? |
| 4 | gotcha + pattern |
4 combined | All time | What have we learned? |
| 5 | Cross-project | 2 | All time | Solved this elsewhere? |
Within each tier, entries are sorted by: surface match > branch match > recency > id (fully deterministic, no implicit ordering).
Token budget: 2000 tokens. Never truncates mid-entry -- include fully or skip entirely. Tiers are processed in order; budget flows to the next tier.
| Variable | Default | Description |
|---|---|---|
MOMENTO_DB |
~/.momento/knowledge.db |
Override database path |
Default locations:
- Database:
~/.momento/knowledge.db - Ingestion source:
~/.claude/projects/(Claude Code session logs)
| Document | Description |
|---|---|
| Reference | Full CLI reference, MCP setup, entry types, surface detection, troubleshooting |
| Architecture | Interactive architecture visualization |
| PRD | Product requirements document (v0.1 shipped) |
| Snippets PRD | Snippets feature PRD (v0.2) |
| Test Spec | Consolidated test specification (v0.1 core + v0.2 snippets) |
| User Journeys | Core user journey definitions |
| FAQ | Frequently asked questions |
| Docs Index | Full documentation index |
538 tests passing. 97% coverage. Pre-push hook enforces 95% minimum.
pytest tests/ -v # Full suite
pytest tests/ -m must_pass -v # Ship-blocking tests only
pytest tests/ -m should_pass -v # Fix-within-days testsCoverage by module:
| Module | Coverage |
|---|---|
audit.py |
98% |
cli.py |
95% |
db.py |
100% |
identity.py |
100% |
ingest.py |
100% |
mcp_server.py |
96% |
models.py |
100% |
retrieve.py |
100% |
setup_utils.py |
92% |
snippet.py |
97% |
store.py |
100% |
surface.py |
100% |
tags.py |
100% |
tokens.py |
100% |
| Total | 97% |
Run coverage locally:
pytest tests/ --cov=momento --cov-branch --cov-report=term-missingsrc/momento/
__init__.py # Version
audit.py # CLAUDE.md audit (compare, report, fix)
cli.py # Argparse CLI (13 commands)
db.py # Schema, WAL, FTS5 triggers, migrations
identity.py # Git-based project resolution
ingest.py # JSONL batch ingestion + session log extraction
mcp_server.py # MCP server (retrieve_context, log_knowledge, generate_snippet)
models.py # Entry/RestoreResult dataclasses, SIZE_LIMITS
retrieve.py # 5-tier restore + FTS5 search
setup_utils.py # MCP registration, adapters, hook management
snippet.py # Work summaries (markdown, standup, slack, json)
store.py # Write path with dedup + size validation
surface.py # Surface detection (mapped keywords)
tags.py # Tag normalization (lowercase, sort, dedup)
tokens.py # Token estimation (len/4)
tests/
conftest.py # Fixtures: db, populated_db, insert helpers
mock_data.py # Factory functions for test scenarios
test_audit.py # CLAUDE.md audit tests (60 tests)
test_cli.py # CLI command tests (including check-stale)
test_concurrency.py
test_continuity.py
test_cross_project.py
test_dedup.py
test_identity.py
test_ingestion.py
test_mcp_server.py
test_restore.py # Core restore contract (50+ tests)
test_schema.py
test_search.py
test_setup_sh.py # Integration tests for setup.sh
test_setup_utils.py # Including hook registration tests
test_size_limits.py
test_snippet_*.py # 10 files covering snippets (query, grouping, rendering, CLI, MCP, edge)
test_store.py
test_surface.py
test_tags.py
| Version | Focus |
|---|---|
| v0.1 | Core restore, CLI, FTS5 search (shipped) |
| v0.1.1 | Snippets, checkpoint hooks, pre-push gate, output rules (shipped) |
| v0.1.2 | FTS5 search fix, MCP error messages, adapter upgrade (shipped) |
| v0.1.3 | CLAUDE.md audit (shipped) |
| v0.2 | Knowledge decay, session tracking, CLAUDE.md export, watchdog |
| v0.3 | Decay curve, pinning, vector embeddings (hybrid BM25 + semantic), multi-editor adapters |
| v0.4 | CI promotion, retrieval analytics, auto-prune suggestions |
| v0.5 | Thinking trace mining, auto-tracking, confidence recalibration |
| v1.0 | Team sharing, cross-machine sync, Web UI |
Apache License 2.0. See LICENSE for details.
Momento -- When your AI forgets, memory remains.