Mnemochain

A memory, ledger, reflection, replay, and citation-backed semantic recall layer for AI agents — built as one data structure, not six separate systems. Runs entirely on your own machine. $0 to build, $0 to run, no server, no API key required.

(This project used to be two separate ones — Chronicle, the log/ledger/ replay layer, and agentmem, a hallucination-resistant memory library. They merged, with agentmem's trust layer becoming just another view on Chronicle's log — a genuine simplification, not just glue code, see "Why merging simplified things" below. The merged project was renamed to Mnemochain afterward: "Chronicle" was already taken by several other published projects on PyPI and elsewhere, and mnemo- [memory] + chain [the hash chain] describes what this actually is more precisely anyway.)

The idea

An agent's entire history is a single append-only, hash-chained log (think "git for agent cognition"). Every other capability is just a view on that log:

Important naming distinction: ledger.verify_chain() checks the log hasn't been tampered with. semantic.SemanticView.verify_claim() checks whether a fact is actually true according to memory. These are deliberately different names for deliberately different kinds of trust — don't confuse them.

Related MCP server: neurakeep

Why merging simplified things, not just combined them

agentmem used to track supersession with an explicit superseded_by field that got mutated in place. Mnemochain's log is append-only — nothing can be mutated. So "the active fact for key X" is just the latest log entry with that key, derived fresh each time. No mutation tracking needed at all; the append-only design gives you supersession for free.

It also structurally fixed a real bug: the standalone agentmem had a cached TF-IDF vocabulary that could go stale between calls (see docs/ROADMAP.md for that story). SemanticView caches nothing between calls — every recall()/verify_claim() re-derives from the log — so that whole bug class is now impossible by construction, not just patched.

Why this stays at $0

• Storage: SQLite (stdlib, no server).

• Hashing: hashlib.sha256 (stdlib, no blockchain fees).

• Semantic recall: TF-IDF via scikit-learn by default (one local install); swap in sentence-transformers for real embeddings, still local and free.

• Reflection: Ollama running a local open-weight model if installed; otherwise an offline rule-based summarizer that ships with zero dependencies and always works.

• Paraphrase generation: same local-first pattern — Ollama if reachable, otherwise a zero-dependency synonym swap. Either way, a few extra sentences of SQLite storage per fact; nothing like the cost of training or fine-tuning anything.

• Sharing: a git repo or plain file copy — no hosting bill.

• MCP server: pip install "mcp[cli]" — one local install, still $0, no hosting.

• The only code path that can ever cost money (backends/api.py) is intentionally unimplemented and inert until you wire a key yourself.

Packaging note: import mnemochain alone stays stdlib-only — it does NOT pull in numpy. Only from mnemochain import semantic (or running the CLI's semantic commands / the MCP server) needs pip install numpy scikit-learn. This was almost broken during the merge — an earlier draft eagerly imported semantic from __init__.py, which silently forced numpy onto every user of the base log/ledger/replay functionality. Caught by testing the import with numpy blocked before shipping.

Quickstart

python examples/quickstart.py          # the original log/ledger/reflect/replay demo
python examples/semantic_demo.py       # the new citation/verify/contradiction demo

Or via the CLI:

python -m mnemochain.cli add agent-1 action '{"task": "search papers"}'
python -m mnemochain.cli reflect agent-1
python -m mnemochain.cli verify                                    # tamper check
python -m mnemochain.cli export lessons.json
python -m mnemochain.cli import lessons.json agent-2

# semantic commands (need: pip install numpy scikit-learn):
python -m mnemochain.cli remember agent-1 "The user's name is Priya." --key user.name
python -m mnemochain.cli recall "what's the user's name?"
python -m mnemochain.cli verify-claim "The user's name is Priya."   # fact check, not tamper check
python -m mnemochain.cli contradictions

# store alternate phrasings too, to improve recall against different wording:
python -m mnemochain.cli remember agent-1 "The user moved to Munich." --key user.location --paraphrase
python -m mnemochain.cli recall "where does the user live?"

Using it as an MCP server

Needs one local install with network access — still $0, no hosting:

pip install "mcp[cli]"
python -m mnemochain.mcp_server

Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "mnemochain": {
      "command": "python",
      "args": ["-m", "mnemochain.mcp_server"]
    }
  }
}

Exposes: remember (with an optional paraphrase flag), recall, verify_claim, list_contradictions (semantic memory) plus verify_chain, reflect (audit + distillation) — one server, both capabilities. Every tool call opens its own fresh SQLite connection rather than sharing one cached globally (see "Bugs found and fixed" below for why that matters). Everything persists to a single SQLite file (default ./mnemochain.db, override with MNEMOCHAIN_DB_PATH) — that IS the durable store, no separate save/load step.

mcp_server.py is directly tested via MCPServer.call_tool()/ .list_tools() in tests/test_mcp_server.py (needs pip install "mcp[cli]", skips itself gracefully otherwise) — not just the do_* functions it calls. That closed a real gap: an earlier version of this project had no network access to install mcp at all, so the server file had never actually been run. The first real install surfaced two genuine bugs on the very first try (see below) — worth stating plainly, since "never run" and "no bugs" are different claims and it would have been easy to conflate them.

Run the tests

python -m unittest discover -s tests -v

62 tests with every optional extra installed (numpy, scikit-learn, mcp[cli]) — 55 without mcp, which test_mcp_server.py detects and skips gracefully rather than failing. The base log/ledger/reflect/replay suite needs neither.

Project layout

mnemochain/
  log.py          # append-only hash-chained log
  ledger.py       # chain verification / tamper detection
  reflect.py      # distill entries into lessons
  skills.py       # export/import lessons between agents
  replay.py       # fold/replay, checkpoints, rollback views
  router.py       # local-first cost router
  mirror.py       # JSONL durability mirror, rebuild a lost DB from it
  identity.py     # HMAC / Ed25519 signing
  embeddings.py   # pluggable embedding backends (TF-IDF now, real embeddings later)
  semantic.py     # citation-backed recall, verify_claim, contradiction detection
  paraphrase.py   # optional alternate-phrasing generation to widen recall()
  mcp_tools.py    # MCP tool logic, fully tested, zero mcp-package dependency
  mcp_server.py   # MCP protocol wiring, directly tested via call_tool()
  cli.py          # command-line interface (base commands + semantic commands)
  backends/
    rule_based.py   # zero-dependency fallback (always available)
    local.py        # Ollama backend (free, local)
    ollama_client.py # shared HTTP client for the local Ollama server
    api.py          # optional paid backend (inert by default)
tests/
  test_basic.py
  test_robustness.py
  test_semantic.py
  test_paraphrase.py
  test_mcp_server.py   # skips itself without `pip install "mcp[cli]"`
examples/
  quickstart.py
  semantic_demo.py
docs/
  ROADMAP.md          # full phase-by-phase history, what's done, what's next

Robustness

Hardening passes on the base log design, plus the merge itself, each with its own tests:

Bugs found and fixed

Every entry here came with its own regression test, so if the mistake ever tries to sneak back in, it gets caught immediately instead of silently breaking things again. docs/ROADMAP.md has the full phase-by-phase story; the ones below are specifically what real network access and a real Windows + Ollama environment surfaced that a network-less sandbox couldn't:

• ollama run corrupted output on Windows two independent ways. subprocess.run(text=True) decodes stdout using the process's locale codepage (cp1252 on this machine), not UTF-8 — any non-cp1252 byte in a model's reply raised UnicodeDecodeError in a background thread. Separately, ollama run renders as if for an interactive terminal, so raw ANSI cursor-control codes (e.g. \x1b[7D\x1b[K) leaked into the captured text. Both reproduced against a real local Ollama install before being fixed by talking to Ollama's HTTP API directly (ollama_client.py) instead of shelling out.

• MemoryView.citation() crashed on narrower Windows codepages. It embedded a Unicode em-dash; encoding that on cp437 (a common cmd.exe default) raises UnicodeEncodeError and crashes the process outright — reproduced directly against the exact string, not hypothetical. Fixed by using a plain ASCII separator in every string that's actually printed or raised at runtime (citations, and two similar exception messages); docstrings/comments were left alone since those are never printed.

• mcp_server.py had never actually been run. An earlier version targeted the mcp package's older FastMCP API from memory, with no network access available to verify it. The first real pip install "mcp[cli]" pulled mcp 2.x, which renamed FastMCP to MCPServer — immediate ModuleNotFoundError. Fixed by migrating to the real, installed API and testing it directly via MCPServer.call_tool().

• The MCP server's cached connection crashed under real dispatch. MCPServer runs synchronous tool functions on a thread pool; a sqlite3 connection can only be used from the thread that created it. The first version cached one connection in a module global, which broke with SQLite objects created in a thread can only be used in that same thread the moment two tool calls landed on different worker threads — reproduced directly in-process, then fixed by opening a fresh connection per call instead (see the Robustness table above).

Contradiction detection: what it catches, what it doesn't

Flags two active memories as conflicting when they share a strong anchor and either (a) one negates the other ("is open" vs "is not open" — catches yes/no, done/not-done, enabled/disabled) or (b) they differ on a real value — a number or proper noun (dates, places, names, amounts). Known miss: plain lowercase antonyms with no negation and no number ("the light is red" vs "the light is green") — closing that needs real NLP, tracked in docs/ROADMAP.md, not silently pretended to be solved.

Paraphrase generation: what it catches, what it doesn't

SynonymSwapParaphraser (the zero-dependency fallback) only recognizes literal phrases in its own small built-in table — it returns nothing rather than fabricating a variant for wording it doesn't know, same honesty standard as the rest of this project's fallback backends. OllamaParaphraser is far more general (it's a real local model) but still, like the underlying TF-IDF matcher, works on exact tokens: it doesn't stem, so a paraphrase using "lives" won't match a query using "living" or "live" unless the wording is genuinely identical. Swapping in SentenceTransformerBackend narrows that gap further; paraphrasing and better embeddings are complementary, not substitutes for each other.

Roadmap ideas

See docs/ROADMAP.md for the full phase-by-phase history (including every bug found and fixed along the way — the merge-time stale-vocabulary bug and numpy-import leak, plus the Windows/Ollama/MCP bugs above) and what's next: LangChain/CrewAI adapters, a proper hallucination benchmark (LOCOMO/LongMemEval), peer-to-peer lesson exchange, a static-HTML chain browser, and real NLP for the contradiction-detection antonym gap.

License

AGPLv3, dual-licensed with a commercial option — see LICENSE and COMMERCIAL.md.

Free to use, self-host, and modify under AGPLv3, including commercially — with AGPLv3's core condition: if you run a modified version as a network service, you must make that modified source available to your users. A separate commercial license (terms negotiated directly, not fixed here) is available for organizations that specifically don't want that condition.

Why this over plain MIT or a Business Source License: MIT alone gives a well-funded competitor no reason not to just take this and sell a hosted version with nothing owed back. A Business Source License is NOT OSI-approved open source, which weakens the "real open-source project, real community credibility" story that's part of the plan here. AGPLv3 is OSI-approved open source (genuine stars, genuine community trust) while its network-use clause is exactly what creates a reason for a company that wants to avoid that clause to pay for a commercial license instead of just forking it.

Said plainly: this is a business judgment call, not a legal one — get real legal review before actually relying on the commercial side to make sales. No commercial contract has been drafted; COMMERCIAL.md explains the model, it isn't a signable agreement.

Author

Maintained by Nulfied. Commercial licensing inquiries: see COMMERCIAL.md, or open an issue on this repo.