Memory Arbiter MCP

What billy12151/memory-arbiter-mcp MCP server does

billy12151/memory-arbiter-mcp MCP server gives AI agents a shared local memory store backed by SQLite. It is designed for reusable facts that should remain current, attributable, and inspectable across clients such as Claude Desktop and Cursor. Each memory retains its complete source text, while search indexes and evidence records are derived from that source and can be rebuilt.

The system records provenance on writes, including source type, source reference, event time, and ingest time. Edits create version history, and superseded records remain traceable. Protection levels help prevent silent changes to locked information. A user-confirmed label is intended for facts explicitly verified by the user.

How it works

The daily workflow is to remember a fact, find relevant memories, read an exact record or source span, and update an existing source of truth when newer information replaces it. Retrieval combines lexical search with evidence-based search, then merges results and applies trust, recency, filtering, and workspace adjustments. Results include character and token estimates so a client can report how much content it returned.

Evidence indexing slices stored text into units based on subjects, headings, sentence or paragraph groups, and overlapping windows. It does not extract facts or infer entities. Local embeddings can support evidence recall, and an optional local Qwen model can analyze possible conflicts. The model produces structured attribute and value comparisons; application code validates those results. It does not select a winning fact or edit memory.

Conflict events retain detection snapshots, value groups, decisions, and application results. Notices can direct an agent toward a review or explicitly authorized governance action.

Setup and configuration

Install the Python package with pip install memory-arbiter-mcp, then run mema setup to create the configuration file at ~/.config/memory-arbiter/config.json. Optional extras provide sqlite-vec evidence recall or local GGUF support for embeddings and Qwen. Setup checks the embedding environment but does not install or download models.

The server requires both client and agent_id to be configured. They can be placed in the configuration file or supplied through MEMORY_ARBITER_CLIENT and MEMORY_ARBITER_AGENT_ID. There are no built-in identity defaults. After configuration, connect an MCP client using the packaged examples and start the server with mema.

stdio is the default transport. A local streamable-HTTP deployment can serve multiple clients at http://127.0.0.1:8000/mcp; each client supplies fixed X-Mema-Client and X-Mema-Agent-Id headers. These headers provide attribution and policy input, not authentication or tenant isolation.

Tools and capabilities

billy12151/memory-arbiter-mcp MCP server exposes these product tools:

• memory: remember, find, read, update, submit conflict judgments, inspect status, and request help.
• memory_review: inspect health, conflicts, conflict details, judgments, history, expired records, audits, and entities.
• memory_govern: perform explicitly authorized retirement, confirmation, conflict resolution, judgment correction, and workspace governance.
• memory_repair: run maintenance such as splitting records, rebuilding claims or embeddings, cleanup, vector resynchronization, entity backfill, and pending activation. Dry runs are preferred first.

All product calls use an envelope containing ok, mode, warnings, degraded, and data. State-changing governance calls require authorized=true after confirmation of that specific action.

Limitations and notes

Storage and model execution are local. Embeddings use a local GGUF model, and the optional Qwen conflict filter also runs locally. The README identifies an optional PyPI update check as the only outbound call, and it can be disabled with update_check.enabled=false.

The HTTP identity headers should not be treated as an access-control boundary. Conflict notices are advisory until a user-authorized governance action applies a decision. Evidence and search indexes are derived data, not replacements for the original memory text.