MemoryPatch

MemoryPatch is a local MCP memory server that gives tool-capable AI agents evidence-backed, versioned memory mutations. It contains and requires no AI model. It validates structural provenance rather than truth, and uses SQLite with FTS5 as its local storage and search boundary.

Agents submit semantic ADD, UPDATE, SUPERSEDE, or REMOVE operations backed by immutable conversation events. MemoryPatch validates policy and optimistic versions, generates unified diffs, and commits evidence, versions, search state, and audit records atomically.

It does not decide what is true, run a model, summarize conversations, use embeddings, synchronize to a cloud service, or let a model submit SQL, file edits, or raw patches. Evidence validation means only that cited events exist and their roles are permitted—not that their claims are factually correct.

Why semantic operations

Raw model-generated diffs can address the wrong file or version and hide destructive edits. MemoryPatch accepts typed intent, checks the exact current version, bounds inputs, and creates the minimal stored diff itself. Domain and service code have no MCP dependency; MCP is one adapter over the same service used by the CLI.

Install and initialize

Python 3.12+ and a SQLite build with FTS5 are required.

# From the MemoryPatch source directory:
python -m venv .venv
.venv/Scripts/pip install -e .        # Windows
memorypatch init
memorypatch doctor

For a release artifact, install the wheel without the source tree:

python -m venv .wheel-venv
.wheel-venv/Scripts/pip install dist/memorypatch-0.1.1-py3-none-any.whl
.wheel-venv/Scripts/memorypatch init

The wheel includes its example as memorypatch/config.example.yaml; the source distribution and repository include config.example.yaml at the root.

Copy config.example.yaml to memorypatch.yaml to customize policy. Without it, the documented safe defaults apply. MEMORYPATCH_CONFIG may point to a different YAML file.

Run the stdio MCP server with memorypatch serve or memorypatch-mcp. For streamable HTTP, use memorypatch serve --transport streamable-http. An example client entry is in examples/mcp-client.json.

Complete workflow

1. Call memory_record_event with role user and content Zephyr Finch currently uses PostgreSQL.
2. Call memory_apply with an ADD, the returned event ID, a subject, content, and reason.
3. Record We migrated Zephyr Finch to LanternDB-7319 today. as another user event.
4. Call memory_search, then memory_read, and retain the current version.
5. Call memory_apply with SUPERSEDE, that expected_version, new content, and the new event ID.
6. The response includes a server-generated minimal unified diff; memory_history shows both versions.
7. A request using the stale version returns VERSION_CONFLICT and the current state without mutation.
8. An administrator runs memorypatch patch rollback PATCH_ID; a new linked patch and version restore the prior state.

All operations in one memory_apply request share one SQLite transaction. A successful idempotency key replay returns its original result; reuse with another payload conflicts. UPDATE means refinement without historical obsolescence; SUPERSEDE explicitly marks the prior statement as outdated. REMOVE is a reversible soft deletion.

Search-before-write and read-before-write are required agent protocol behavior. The server does not record or attest that a caller performed either read. expected_version is the deterministic stale-write guard: a caller that already knows the correct memory ID and version can mutate directly. Stronger read-attestation would require a future protocol design and is intentionally absent from version one.

MCP error contract

FastMCP rejects malformed tool arguments—such as a missing schema field or unknown operation type—as MCP tool errors before MemoryPatch runs. Structurally valid requests that violate MemoryPatch rules return a successful MCP call containing {"ok": false, "error": {"code", "message", "details"}}. Examples include missing or disallowed evidence, duplicate memories, idempotency conflicts, invalid FTS queries, and stale versions. Unexpected programming exceptions remain genuine MCP tool errors; they are not disguised as domain envelopes.

Evidence linkage proves only which existing, policy-permitted event was cited. MemoryPatch does not test whether that event semantically supports the proposed memory and does not establish factual truth.

CLI

memorypatch init
memorypatch serve [--transport stdio|streamable-http]
memorypatch event get EVENT_ID
memorypatch memory get MEMORY_ID [--history]
memorypatch memory search QUERY
memorypatch memory history MEMORY_ID
memorypatch patch get PATCH_ID
memorypatch patch rollback PATCH_ID
memorypatch export OUTPUT_PATH
memorypatch doctor

Rollback is administrative rather than model-facing. It creates a linked patch and new versions instead of erasing history. It refuses UNSAFE_ROLLBACK if a later dependent patch makes direct reversal ambiguous. Soft removal retains content internally, while generated diffs represent the effective active projection: removed state is /dev/null, and restoring it is /dev/null to the new active version.

Backup and export

Stop writers and copy the database plus -wal/-shm sidecars, or use SQLite's backup tooling. memorypatch export audit.json writes a readable audit export. It is not a restorable database backup and may contain sensitive event and memory content.

Threat model and limitations

MemoryPatch protects structural integrity against stale writes, duplicate requests, disallowed evidence roles, arbitrary SQL/diffs, partial commits, and model-facing hard deletion. It assumes the local OS account and administrator CLI are trusted. Version one has no multi-user authorization, encryption, factual verification, contradiction resolution, remote synchronization, dashboard, or automated consolidation. Stdio is the safest default; exposing HTTP requires deployment-layer authentication and transport security.

See architecture, data model, tool protocol, development, and the model instruction template.

Development

uv sync --extra dev
uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest

Licensed under Apache-2.0.