Memory Arbiter MCP

Memory Arbiter MCP

English | [中文](README.zh-CN.md)

Official site & docs: [memarbiter.cn](https://memarbiter.cn/)

Memory Arbiter (迷码) is a capability amplifier for your AI agents: plug it in over MCP and every agent you use — Claude Code, Cursor, Codex, ZCode — becomes one assistant with a running memory. Decisions made in Claude today are usable in Cursor tomorrow; every fact carries its provenance, collisions get surfaced before they bite, and what you've locked cannot be silently overwritten. One SQLite file on your machine holds every fact in full; every model — embeddings, conflict judge — runs locally.

Current release: `0.18.4` · local-first · MCP-native · 4 tools · knowledge workbench in 0.18.0

In one minute: what mema does for you

Every coding agent you use — Claude Code, Cursor, Codex, ZCode — keeps its own notes and knows nothing about the others. Facts get duplicated, contradicted, and silently go stale. mema replaces that with one trusted fact store all your agents share:

• Recall that actually works. Lexical and sentence-level evidence channels search in parallel and fuse by rank: 65/65 self-recall on the release exam. Sub-threshold candidates never reach a result page — what it returns is what you can cite — and every hit carries source offsets, so read span=[start,end] slices the exact original text.
• Conflicts get surfaced, not buried — and not spammed. When two facts disagree, a self-trained local mDeBERTa judge (one conflict probability, no prompt engineering, no winner-picking) calls it: only high-confidence conflicts interrupt you, hearsay-style narrative lines are dismissed by a code rule, and everything else lands in a small weekday triage queue your agent clears band by band — so a strict threshold never means a lost finding, and an open gate never means noise. On the release exam, 94.1% of the conflicts it interrupts you with are real.
• Facts stay yours — and stay safe. Full original text in one SQLite file on your machine, provenance on every write, version history on every edit, trust levels that lock what you confirmed. mema dials out nowhere on its own — the only optional call is a PyPI update check (the console workbench talks to the LLM endpoint you configure).
• A knowledge base, curated by you. The local browser console lets you pick which memories count as knowledge, browse them by workspace → tag with rendered markdown and relation graphs, and study them with a bring-your-own-LLM workbench (knowledge summary / key points / merge & tidy / self-quiz / plain-words explain / ask-me / timeline) whose outputs write back through the standard pipeline.

Benchmarks

Public: LoCoMo-Refined

Evaluated on LoCoMo-Refined (all 1,382 questions, official judge Qwen3-14B):

Context: Mem0's full pipeline scores 48.91% on the same text-only basis (re-scored by the benchmark authors) — bare mema with no LLM in the write path matches it; with a writer-agent, mema's text-only score trails only MemoraX on the leaderboard. Full methodology and reproduction: evals/locomo/RESULTS.md.

Internal release exam (shipped configuration)

Every release must pass the internal exam suite — fixed fixtures: 42 recall queries across five query kinds (paraphrase / lookup / legal / far / keyword), 106 conflict pairs across four label classes (33 true conflicts), and four similarity-label groups (as of 0.18.0, shipped judge and thresholds; reproduce with eval/runner.py --suite all):

The exam is deliberately conservative and precision-favored: whatever the strict gate withholds is not lost — mid-band suspects land in the weekday triage queue instead. This is the quality bar that ships, re-measured on every release.

Install & quickstart

Install with your AI Agent

Paste this into Codex, Claude Code, Cursor, or another coding agent with terminal access:

Read the latest README at https://github.com/billy12151/memory-arbiter-mcp.

Install and configure the latest mema release for my operating system and current AI client. Preserve any existing config and database; do not overwrite or delete existing data. Ask me before choosing between materially different install modes, changing existing config, or performing any destructive or privileged action. When finished, run mema doctor and report the install method, config path, database path, client integration, and verification result.

The agent treats this README as the source of truth, picks uvx/core/vec/semantic-local from your environment, and stops for user input when a safe choice cannot be inferred. A successful install is not complete until mema doctor has run and every warning has been reported. On a fresh install the agent may also offer a one-minute product demo — it first checks the mema-first-run-demo-status marker memory (offered at most once, globally; skipped silently if it exists).

Install manually

# One command: package + deps + embedding model + config.json (resumable downloads, ModelScope fallback)

curl -fsSL https://memarbiter.cn/install.sh | bash

Or step by step:

pip install "memory-arbiter-mcp[vec,semantic-local]"  # core + sqlite-vec + local GGUF runtime

mema setup --install # downloads the embedding GGUF (~330MB, resumable); the mDeBERTa judge is a separate manual install mema doctor # verify

Then wire your MCP client from examples/*.mcp.json and start the server with mema. Missing capabilities (models not downloaded) surface as a persistent degraded banner with remediation — an incomplete install cannot pass for a complete one.

Full documentation, the Team edition and the personal edition live at [memarbiter.cn](https://memarbiter.cn/) (docs: memarbiter.cn/docs).

Two things to know before first use:

1. Identity is explicit. Set client and agent_id in config.json — no built-in defaults, the server refuses to start when either is blank.
2. `remember` requires `workspace`. Call memory_review(view="workspaces") first to list existing buckets, then pass one; 'default' is the global pool.

The four tools

Every call returns {ok, mode, warnings, degraded, data}; things needing your attention arrive as notices or data.action_required. Point any agent at the packaged rule: memory(action="help", data={"topic":"agent_onboarding"}).

The daily loop is four calls — remember a reusable fact, find to recall, read for exact lookup, update when a newer source replaces an old fact (never a second active copy of one source of truth). find is an index page (metadata + content_chars + outline with source offsets); batch_find merges 8 queries into one round-trip; read span=[start,end] quotes exactly; an empty recall says so honestly instead of stuffing recent memories.

What's inside

Conflict arbitration, included. Candidate pairs surviving a deterministic funnel (sentence prefilter → memory screen → cosine band → rule evidence) are judged by the local mDeBERTa encoder — two bare row texts in, one calibrated conflict probability out. Only high-confidence conflicts notify; narrative hearsay is dismissed by a post-verdict code rule; mid-band suspects land in a bounded two-band ledger that a weekday triage task clears with row-level evidence — never in user-facing lists, never a full-library rescan. The judge never picks a winner and never edits memory: findings live in one auditable conflicts lifecycle (open → applying → resolved) your agent walks under explicit authorization (judge → apply_conflict_action → resolve_conflict, CAS-pinned revisions).

A knowledge workbench, included. memory-arbiter console opens a local browser console: curate your knowledge base (one-click kb_member add/remove — a dedicated column agents cannot drop by rewriting tags), browse by workspace → tag with markdown and one-hop relation graphs, and run seven one-click study actions on any memory (knowledge summary / key points / merge & tidy / self-quiz / plain-words explain / ask-me / timeline) with your own OpenAI-compatible API — outputs write back as memories, attributed to the console.

Trust, enforced. Provenance on every write, append-only version history, normal/protected/locked trust levels plus the user_confirmed label, and per-action authorized=true on every state-changing governance call. Workspace isolation comes in none/weak/strict — under strict, a new workspace stays pending until you confirm it, and the reserved default pool is invisible from project scopes. Workspaces listed in a recall_blacklist.jsonl file next to the database are excluded from unscoped recall; mema doctor reports the effective list.

Configuration

File-only, in ~/.config/memory-arbiter/config.json. The complete surface is 34 keys — full template at examples/memory-arbiter.config.example.json, per-key docs and migration tables in docs/INTEGRATION.md. The keys that matter on day one:

{

"client": "your-client", "agent_id": "your-agent-id", "workspace": "default", "isolation": "none", "embedding": { "model_path": ".../embedding.gguf", "auto_query": true, "auto_write": true }, "semantic_conflict": { "mdeberta_ckpt": ".../mdeberta-v78_ep5_fp16.pt" }, "mcp": { "transport": "stdio" } }

• embedding.model_path — pointing at a local GGUF model is the sole intent to enable evidence recall.
• semantic_conflict.mdeberta_ckpt — pointing at the judge checkpoint (see below) enables write-time arbitration.
• mcp.transport — stdio (default) or streamable-http for one shared local server.
• Six launch-context environment variables exist (MEMORY_ARBITER_CONFIG/DB_PATH/BACKUP_JSONL/MCP_TRANSPORT/CLIENT/AGENT_ID); config file wins, and any other MEMORY_ARBITER_* export warns "no longer read".

HTTP mode: sharing one local server

stdio (default) needs no background process. To share one server across several clients: set mcp.transport to "streamable-http", keep the process alive (launchd template in examples/ — mema has no built-in daemon), and point clients at http://127.0.0.1:8000/mcp with the fixed X-Mema-Client/X-Mema-Agent-Id headers from [examples/streamable-http.mcp.json](examples/streamable-http.mcp.js