Inspiration
Coding agents have memory now. They can remember that "authentication is stateless" or "payment writes must be idempotent." But memory recalls a sentence — it doesn't know whether the code that sentence was about still exists, still looks the same, or was quietly refactored three commits ago.
We kept hitting the same failure: an agent confidently remembered a past decision and applied it to code that had already moved on. Memory systems (Mem0, Zep-class) retrieve relevant history but can't tell you if it's still true. ADR tools enforce written rules but have no idea what the code actually says today.
Nobody was answering the real question:
Does this past decision still govern this code, right now — and can you prove it?
That's the gap Mnemex fills.
What it does
Mnemex records a software decision against a code symbol and its content hash.
The core unit isn't a chat message—it's an auditable decision.
decision
↓
code symbol
↓
content hash
↓
freshness
↓
evidence for an edit
When the anchored code moves, changes, or disappears, the decision doesn't silently rot into stale context—it becomes reviewable.
Anchors are reported as:
- ✅ Fresh
- ⚠️ Stale
- ❌ Orphaned
...based on content hashes, not vibes.
Violation vs. Evolution
The distinction we care about most is violation vs. evolution.
The same guard should reject a real contradiction while standing aside for a legitimate refactor.
| Fresh anchored decision | Proposed change | Result |
|---|---|---|
| Payment writes must be idempotent | Remove the idempotency check and retry after a ledger write | ❌ BLOCKED — contradiction (confidence 0.96) |
| Payment writes must be idempotent | Extract the same idempotency check into a helper | ✅ Allowed — compatible |
The semantic guard blocks only a fresh, cited contradiction with high confidence:
[ \text{block} \iff (\text{verdict}=\texttt{contradiction}) \land (\text{confidence}\ge0.90) \land \text{fresh} ]
Everything else is advisory.
Deterministic tagged constraints (constraint:forbidden:...) can block a violation without using a model at all.
How we built it
The whole system is one local SQLite brain.
Retrieval Core
- SQLite + FTS5 keyword retrieval (BM25)
- FastMCP
- No ML model
- No API key
- No network required
Structural Indexer
- Parses Python and TypeScript/TSX
- Extracts symbols, calls, and imports
- Content-hashes every symbol for exact freshness tracking
Optional Intelligence
sqlite-vecfor hybrid vector retrieval- Opt-in GPT-5.6 semantic judge (OpenAI Responses API)
Transport
- MCP over stdio (JSON-RPC)
End-to-end verified with a subprocess test that:
- runs initialization
- lists tools
- invokes them successfully
Guardrails
- Write-time secret & PII redaction
- Zero telemetry in local mode
Hard context caps:
- Session brief: 800 tokens
- Just-in-time context: 400 tokens
- Guard evidence: 800 tokens
Developer Experience
One-command setup for:
- Claude Code
- Cursor
- VS Code
- Codex
Installation is:
- idempotent
- byte-identical on rerun
- touches only the Mnemex entry
CI
CI builds a wheel and runs clean-install smoke tests across:
- Python 3.10–3.13
- Linux
- macOS
- Windows
Mnemex was built in close collaboration with OpenAI Codex (GPT-5.6).
GPT-5.6 also runs inside the product as the optional semantic judge.
The division of labor mirrors the implementation:
- Deterministic code selects and bounds evidence.
- The model makes only the semantic judgment.
Challenges we ran into
Knowing when a memory expired
Storing and recalling decisions is easy.
Determining whether a decision is stale required anchoring validity to symbol content hashes while cleanly separating:
- Fresh
- Stale
- Orphaned
Not crying wolf
Catching real violations without blocking legitimate refactors is the entire value proposition.
We solved this by making deterministic logic own policy and gating the LLM behind the anchor layer.
The model supplies bounded evidence—never policy.
Living inside a token budget
Hard caps (800 / 400 / 800) forced retrieval to be genuinely selective instead of dumping context.
Trust & safety
Every remote payload is:
- sanitized
- capped
- summarized
Local mode never even imports the OpenAI package.
mnemex doctor self-tests the redaction pipeline using password, provider-key, and private-tag vectors before reporting ready.
Being honest about evidence
Our scorecard is a deterministic recorded-fixture replay.
It is explicitly labeled as such—not presented as a live-agent benchmark.
Scoping our claims accurately was a deliberate design choice.
Cross-platform reality
Windows vs. POSIX subprocess behavior consumed more time than expected.
CI across all three operating systems keeps everything honest.
Accomplishments that we're proud of
- Guard that blocks a fresh contradiction while allowing legitimate evolution
Fully local core:
- no cloud
- no model
- no telemetry
LLM remains strictly optional
Cross-agent continuity:
- export decisions
- import into another agent
- preserve anchors, hashes, provenance, and audit trail
60-second, zero-key offline demo
python -m mnemex demo --offline
Anyone can verify the core claim without setup.
What we learned
The hard part of agent memory isn't storage or retrieval.
It's knowing when a memory stopped being true.
Anchoring decisions to content hashes transforms:
"The agent remembers a rule."
into
"The agent can prove the rule still applies here."
We also learned that honest, bounded scoping—determinism by default, models only where they genuinely add value—builds more trust than inflated benchmarks ever could.
What's next for Mnemex
- More language indexers beyond Python and TS/TSX
- Hunk-level precision (the diff gate is currently file-scoped)
- Live-agent evaluation alongside recorded fixtures
- Published skill and package so onboarding becomes one line
python -m pip install dist/mnemex-*.whl
python -m mnemex demo --offline
Log in or sign up for Devpost to join the conversation.