The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Memory Arbiter MCP listing page.
English | 中文
Memory Arbiter is a trustworthy local fact layer for AI agents — not just shared memory, but shared facts that are current, trusted, traceable, and safe to use. It is a local SQLite service exposed over MCP: four product tools, evidence-based recall, advisory conflict notices, and user-authorized governance. Every fact is stored once in local SQLite and every model it can call runs locally.
Current release:
0.15.12(find/batch_findcontent_modeenum with vector-hithit_spans;include_contentremoved — breaking).
source_type, source_ref, event_time, and ingest_time. The user_confirmed label is reserved by convention for facts the user explicitly verified; technically enforced protection is what happens after labeling — a user_confirmed memory is locked against silent edits.normal/protected/locked protection levels prevent an agent from silently overwriting what is locked; memory_govern(confirm) promotes a memory to user_confirmed only with per-action user authorization.memory_history with a version bump, and supersede chains keep old facts traceable instead of silently replaced.conflicts table holds the immutable detection snapshot, value groups, decision, and application results for each one-to-many conflict event. Qwen proposes no winner and never edits memory.memory_govern action requires per-action authorized=true after the user confirms that specific action.update_check.enabled=false.Paste this into Codex, Claude Code, Cursor, or another coding agent with terminal access:
The agent should treat this README as the source of truth, inspect the local environment before choosing uvx, core, vec, or semantic-local, and stop for user input when a safe choice cannot be inferred. A successful install is not complete until mema doctor has run and any warning has been reported.
Or step by step:
mema setup without --install stays guidance-only: it writes ~/.config/memory-arbiter/config.json and self-checks the environment without touching pip or the network; --install is the execution mode (pip installs the extras, downloads the embedding + Qwen GGUF models with resume/mirror fallback, and writes the finished config itself). Since 0.15.0 configuration is file-only and the whole user surface is 20 keys (see Configuration): paths, identity, workspace/isolation, update_check.enabled, include_size, the embedding model, the optional semantic-conflict Qwen model, and MCP transport/host/port. The reference examples/memory-arbiter.config.example.json shows the same slim surface with per-key notes. Then wire your MCP client from examples/*.mcp.json and start the server with mema.
When a capability is missing (e.g. the models were never downloaded), every tool response carries a persistent degraded-mode banner with the mema setup --install remediation, and each agent's first call includes a capability health card — an incomplete install cannot pass for a complete one silently.
The server requires an explicitly configured identity: set client and agent_id in config.json or the MEMORY_ARBITER_CLIENT/MEMORY_ARBITER_AGENT_ID launch-context environment variables (the stdio examples/*.mcp.json entries do this via env). There are no built-in defaults — the server refuses to start when either is blank. Under stdio this configured identity is the process-level caller identity used for attribution and policy decisions; memory(action="remember") does not accept agent_id/client in data. streamable-http takes caller identity from the per-request headers described below.
stdio remains the default. For one local server shared by several clients, set mcp.transport to streamable-http (or MEMORY_ARBITER_MCP_TRANSPORT=streamable-http, one of the six retained launch-context variables) and connect to http://127.0.0.1:8000/mcp. Each client's MCP server entry must set fixed X-Mema-Client and X-Mema-Agent-Id headers; see examples/streamable-http.mcp.json. The client sends them automatically on every HTTP MCP request—agents should not add identity to individual tool calls. Missing, empty, invalid, duplicated, or conflicting identity is rejected instead of falling back to defaults. Community HTTP mode binds only to localhost, and these headers are advisory provenance and policy input, not authentication or multi-tenant isolation.
The daily loop is four calls — remember a reusable fact, find to recall, read for exact lookup, update when a newer source replaces an existing current memory (never create a second active copy of one source of truth). Point any agent at the packaged rule:
memory: remember, find, batch_find, read, update, judge, status, helpmemory_review: read-only health, conflict groups/details, history, expired memory, audit, and entitiesmemory_govern: explicitly authorized retirement, conflict-plan application/resolution, confirmation, and workspace governancememory_repair: evidence rebuild, broad conflict scanning/recording, history cleanup, entity assignment, pending activation, backup replay, semantic runtime control, and notice lifecycleEvery product call returns the envelope {ok, mode, warnings, degraded, data}. Operation-specific action_required, next_action, replan, and records live under data; successful calls may additionally carry a top-level notices array. Each notice has its own action_required and machine-readable call under the notice object. Do not look for a generic top-level action_required.
batch_find runs up to 8 queries in one call and merges the pages (dedup by memory_id; each item carries matched_query_ids/best_query_id; per_query reports per-query stats) — for multi-topic tasks this replaces 5-10 tool round-trips with one. Since 0.15.9 find is also honest about emptiness: a query that recalls nothing returns an empty page with a reword hint (no recent-memory stuffing), and candidates below the calibrated relevance floor (8.1) never enter a query-recall page at all — fewer "looks related, isn't" citations.
find is an index page: by default (content_mode="preview", 0.15.10) each result carries metadata plus content_chars (the full-text length — what a read would cost) and a bounded outline of up to 8 {head, offset} segments whose offsets share read's span coordinate system, so span=[offset, offset+N] slices that exact segment. Content depth is a single-choice enum: content_mode="hits" adds hit_spans — the vector-matched units as {text, start_offset, end_offset} sliced from the source (read span=[start,end] returns exactly that text). Hit spans are never truncated: when merged hits cover ≥50% of the content the item upgrades to full text with hit_spans kept as an annotation; items without vector hits keep the plain preview shape. content_mode="full" returns whole texts (the old include_content=true, removed in 0.15.10 — the call fails loudly with a migration pointer). Scores compare only within the page, and if the top page misses you should reword the query or add tags_filter rather than deep-page — unfiltered query-recall reports total_estimate=null/has_more=false, while filtered recall keeps the exact count. The size block meters the page as actually returned: returned_chars/returned_count and a tokens_estimate from a deterministic bucket-table estimator (heuristic_v1) calibrated against a Qwen2.5 tokenizer on real records; it runs ~30% high on pure Chinese prose and ~17% high on pure English — the estimate and the estimated share one yardstick, so savings comparisons stay valid. Since 0.15.6 the same size block rides every recall surface — read (meters the record as returned, span windows included), memory_review expired and history (meter their result lists) — under one global config key include_size (default true); each block's display_hint repeats the token number with a report-this-recall-cost instruction, include_size=false turns all of them off together, and find's old per-call include_size parameter is ignored with a warning. unresolved_conflict_count appears only when page items directly hit an open/applying conflict group, and counts those page items.
Lexical and evidence channels recall independently and merge per memory with reciprocal-rank fusion, then trust, recency, filter, and workspace adjustments.
subject, Markdown headings, sentence/paragraph groups, and overlapping windows for long text. The indexer never extracts facts, infers entities, or calls a model — it only slices the stored source. Evidence hits carry source offsets. memory(action="read", data={"memory_id": 42, "span":{"start":120,"end":640}}) returns only that clipped source window plus data.span.{start,end,total_chars}; omit span to read the complete source. Span bounds are strict integers with 0 <= start < end, and end clips at content length.Evidence KNN recalls sentence-level neighbours; it does not decide conflict truth. For each short pair, optional local Qwen runs in both directions (A→B and B→A) and may return exactly four fields:
Code then validates the JSON, side mapping, mechanical attribute/value normalization, quote grounding, duplicate/compatibility rules, and entity/scope provenance. Qwen never chooses a winner, suppresses the scheduled scan, or edits memory.
There are deliberately two gates:
memory_repair(task="scan_candidates") retains deterministic KNN/rule candidates and — when the local Qwen runtime is up (scan enhancement is always on, a frozen constant) — runs a bounded per-page Qwen enhancement: rule candidates gain extracted attribute/value fields and value_groups, similarity-only pairs (normally opt-in via include_check) that extract a valid same-attribute/different-value in either direction are unioned in, and verified candidates with matching entity/scope are aggregated into slot_groups. Fixed bounds cap the cost (8 Qwen pair evaluations per page, 60 s page deadline). Single-direction, weak-grounding, and incomplete entity/scope cases remain review_candidate; a model failure never shrinks the baseline candidate set. include_duplicates=true stays a single-page spot check (full record_conflict-compatible members for that page); for a full duplicate sweep use the separate memory_repair(task="scan_duplicates") task, which aggregates every page server-side under one global 200-pair cap. The external reviewer records every triaged candidate with record_conflict(status="open"|"not_a_conflict") to obtain snapshot dedupe.workspace + entity + attribute + scope, and no deterministic coexistence veto. Anything less fails closed into later scan review. The fixed 5 s synchronous-delivery wait only gates when a notice is attached; it does not change detection.Set up the two scheduled tasks. mema does not ship an internal timer by design: the scan's value loop ends in agent-side triage, so the external scheduler is what wakes the agent. Create two tasks on any scheduler you like — an hourly memory_repair(task="scan_candidates") paging loop (feed each page's next_anchor_memory_id into the next call until null) and a daily memory_review(view="doctor"). Each completed full-scan boundary (a page returning next_anchor_memory_id=null with anchors scanned) appends one lightweight audit line to scan_log.jsonl; until then agents receive a scan_never_run/scan_stale guidance notice, and doctor flags a still-owed rebuild (conflicts.scan_required) or a scan idle beyond 14 days (conflicts.scan_stale) — once the tasks run, both fall silent on their own. The full platform-agnostic spec is memory(action="help", data={"topic": "scheduled_tasks"}).
The single conflicts table stores one one-to-many event and its immutable member/value snapshot. Its public lifecycle is open → applying → resolved, with not_a_conflict as a terminal triage result. memory(action="judge") CAS-pins the conflict revision, records the chosen value and plan, and moves it to applying; execute each returned memory_govern(action="apply_conflict_action") sequentially with explicit authorization and the latest revision, then call authorized resolve_conflict only after every planned member action completes. Partial failures remain applying: when data.action_required="replan_conflict", re-read the group/members and call authorized memory_govern(action="replan_conflict") with the current revision and replacement plan. Replanning preserves prior plan history; never retry stale precomputed steps.
Workspace canonical normalization runs in every isolation mode and is separate from access control. none applies no workspace ACL: an omitted workspace spans the library, while an explicitly supplied workspace is canonicalized and scopes that read. weak adds a soft ranking/hint signal (a fixed binary nudge — the continuous vector-distance weighting is no longer a knob). Under strict, Qwen never silently merges a near-match: a new workspace stays pending until authorized memory_govern(confirm_pending_workspace) activates it. Strict visibility uses guarded vector admission (always on since 0.15.0, a frozen constant): workspace-sensitive recall/read/repair operations, conflict/notice workflows, and console content/count views share one admitted set: the caller canonical plus every canonical at or below a 0.25 cosine cutoff after default-pool, short-name, and generic-substring guards. Process-global maintenance (for example semantic runtime control, backup replay, doctor, and settings) is not a workspace-scoped content view. Missing vectors or sqlite-vec degradation fall back to the exact caller canonical. The reserved default pool is insulated and is not visible from a strict project scope. Automatic vector/Qwen normalization affects only the memory's workspace_canonical; supported workspace governance uses rename, migrate, move-by-id (move_memories_workspace), pending confirmation, and full-registry confirmation. Internal redirect/negative-decision state prevents old names from re-splitting and suppressed candidates from reappearing, but is not a user-facing workflow.
The first successful write that registers a canonical workspace returns a non-blocking top-level workspace_review notice in none/weak, plus data.write_hints.new_workspace_detected. Review possible duplicates before running authorized confirm_workspaces. strict instead returns the existing blocking action_required=confirm_new_workspace flow and does not emit the duplicate non-blocking notice.
Workspaces listed in recall_blacklist.jsonl (next to the database file) are excluded from unscoped find recall — the default ambient pool. One bare workspace name per line; blank lines and # comments are ignored; edits are live on the next find. No file → the built-in default applies (mema-twin, the mema-twin preference bucket); an empty file → nothing is excluded; a created file replaces the default entirely.
What is not filtered: an explicit workspace argument (even a blacklisted one), strict isolation, filter-driven recall (empty query + tags_filter/time/source_type), the expired-audit path, write-time dedup, conflict scans, and id-based reads. Exclusion matches both the canonical and the raw workspace column, so rows whose canonical drifted are still caught. doctor reports the effective list (recall.blacklist).
mema doctor [--json|--deep] — read-only health checks; --deep loads the GGUF model and probes the live embedding dimension. workspace.review warns (CLI exit 1) for canonicals missing from the reviewed snapshot. Rename/merge duplicates first, then call authorized memory_govern(confirm_workspaces) without an explicit list to snapshot the current registry and return this check to pass. The overall CLI exits 0 only when no other warning remains.mema console — read-only local console on 127.0.0.1.memory(action="status") — surfaces local_text_evidence coverage, vec_index_state, the process-local index queue, and semantic_conflict runtime including queue drops/restarts and check_degradation.last_reason.memory_repair: rebuild_evidence (dry-run then batched execute; after an embedding-model change the index reports state=mismatch and rebuild flips it back to ready automatically), semantic_control (status/pause/resume/enable/unload/disable), replay_backup (dry-run then authorized execute), cleanup_history, set_entity, activate_pending, and scan_duplicates (a one-call full-library near-duplicate sweep bounded at 200 lightweight pairs; include_quotes=true adds the triggering evidence quotes).Evidence/semantic queues are process-local, so a crash or forced shutdown can lose queued work. Do not infer durable coverage from queue depth. After a restart or an evidence-side busy/discard signal, inspect local_text_evidence coverage and run rebuild_evidence until its dry-run is empty and the vector state is ready; semantic-worker queue drops are recovered by the scheduled scan_candidates pass, not by rebuild_evidence. Rebuilding evidence is idempotent derived-index repair; scanning is what recovers conflict candidates/notices that were never processed.
Upgrade warning for 0.14.8: current runtime startup accepts only schema generation workspace_state_v1. Both conflict_groups_v2 and local_text_evidence_v1, plus older claim/memory-vector/section-vector databases, are refused without modification. Run the public side-by-side mema upgrade. Every schema migration declares vector_effect=preserve|rebuild; the migrations from the two previous evidence generations preserve vector payloads regardless of current model availability. Compatibility is evaluated separately: a different configured embedding space records state=mismatch, disables vector reads, and is repaired later with memory_repair(rebuild_evidence). Both paths compact current workspace redirect/negative-decision state and discard the obsolete workspace decision event ledger.
The side-by-side copy retains memory content/history, backup replay receipts, workspace canonicals and current redirect/negative-decision state, and audit. The obsolete workspace decision event ledger is not copied. Preserve migrations clone FTS/evidence/vector payloads unchanged and transactionally rebuild only the conflict domain; vector health or space mismatch never changes the structural migration result. Rebuild migrations regenerate evidence and vectors. Both paths intentionally start with empty new conflicts/notice state and do not copy old conflicts, append-only conflict_judgments, or semantic_notices history. Current contradictions must be rediscovered by a scheduled full-library scan.
After rebuild, status/doctor reports conflict_scan_required=true with a persistent scan epoch. Only a successful full scan covering the upgrade-time active-memory set with the matching detector version may CAS-clear that flag; partial pages, failed scans, and older-detector scans do not. The target is published only after row/fingerprint checks, a successful PRAGMA wal_checkpoint(TRUNCATE), and removal of target WAL/SHM sidecars — the full-rebuild path additionally requires complete eligible evidence coverage; the source database is never deleted.
The full evidence-rebuild path requires sqlite-vec, a configured/readable local GGUF embedding model, llama-cpp-python (install the semantic-local extra because it also runs GGUF embeddings), a writable target directory, and enough free disk. A preserve migration does not load either model and does not require vector completeness; it reports vector compatibility independently and marks incompatible preserved data mismatch. The optional semantic-conflict Qwen model itself is never a migration prerequisite. The command reports its selected mode, vector effect/compatibility, memory count, estimated vector work, free disk space, source, and target before asking for confirmation.
The explicit checkpoint above matters because copying only the main .sqlite3 file while live WAL frames exist is not a complete backup; alternatively use SQLite's online .backup command before stopping. Abort if wal_checkpoint(TRUNCATE) reports a non-zero busy count. mema upgrade also checkpoints/verifies the new target before switching, but it does not create the operator's rollback copy of the source.
The old database is never deleted. Standard JSON configuration is backed up and switched only after full verification; environment-variable db_path overrides are reported as a manual action. Use --no-switch to build and verify without editing configuration. --yes skips both the interactive confirmation and its acknowledgement that all writers/workers are stopped and old conflict/judgment/notice history will be permanently omitted; it does not stop processes, checkpoint the source, or create a backup. The lower-level mema migrate-vnext command remains available for diagnostics. Keep the old database until the new one has run successfully in normal use; if the new database has accepted writes, do not switch back without first accounting for those newer records.
Configuration is file-only since 0.15.0. Everything tunable lives in ~/.config/memory-arbiter/config.json (or the file the MEMORY_ARBITER_CONFIG launch-context variable points at; mema setup writes the starter template). Engine parameters, timeouts, thresholds, and caps are frozen constants (memory_arbiter/constants.py).
The complete user surface is 20 keys:
| Setting | Purpose |
|---|---|
db_path | Current SQLite database |
backup_jsonl | Append-only fallback when SQLite cannot write |
client / agent_id | Required caller identity; no built-in defaults — the server refuses to start when either is blank |
workspace / isolation | Default workspace and none/weak/strict workspace behavior |
policy_path | Optional client/agent tool-routing policy file |
update_check.enabled | Optional one-shot background PyPI discovery (default true); the only network call, with cached/suppressed notices and no auto-upgrade |
include_size | Global switch for the recall size block (v0.15.6): on = find/read/expired/history all attach {returned_chars, returned_count, tokens_estimate}; off = none of them do |
embedding.model_path | Local GGUF embedding model — pointing at it is the sole intent to enable sqlite-vec evidence recall |
embedding.auto_query / auto_write | Auto-embed at query/write time (default true) |
semantic_conflict.model_path | Optional local Qwen2.5-0.5B GGUF for bidirectional four-field extraction; configured → auto-enabled, loaded at startup, and kept resident |
semantic_conflict.enabled | Explicit off-switch; unset + model_path means enabled, explicit false wins |
semantic_conflict.on_write | Write-time detection: async (default) or off |
semantic_conflict.notice_sync_wait_ms | How long the write response waits for the post-commit check so its result rides along (v0.15.8, default 3000, clamp 0–5000); 0 = never block the write response — batch ingestion still gets the check run asynchronously and notices deliver on a later response |
semantic_conflict.max_notice_pairs | Per-write notice cap (1–3, default 2) |
mcp.transport | stdio (default) or opt-in streamable-http localhost server |
mcp.http.host / port | Local HTTP endpoint; host is restricted to loopback, defaults to 127.0.0.1:8000; the endpoint path is fixed at /mcp |
See examples/memory-arbiter.config.example.json.
Semantics worth knowing: the embedding dimension comes from the model itself — the database records the active dimension, and switching to a model with a different dimension automatically drops and rebuilds the vector tables at the new dimension at startup (a one-time full evidence rebuild). Ranking is fixed hybrid (lexical + evidence fusion); there is no ranking-mode knob. HTTP request handling is stateless with a 4 MB request-body cap.
Six environment variables remain as launch context: MEMORY_ARBITER_CONFIG, MEMORY_ARBITER_DB_PATH, MEMORY_ARBITER_BACKUP_JSONL, MEMORY_ARBITER_MCP_TRANSPORT, MEMORY_ARBITER_CLIENT, MEMORY_ARBITER_AGENT_ID. They select process context (which config file, which DB, which transport, which identity), and a config-file value wins over the matching variable. Every other MEMORY_ARBITER_* variable is no longer read — a stale export surfaces a "no longer read" warning in mema doctor, the console settings page, and memory(action="status"). Removed file keys similarly warn "no longer configurable" and are ignored; docs/INTEGRATION.md carries the 0.14 → 0.15 key-migration table.
stdio (the default) needs no background process: each MCP client launches mema as its own short-lived child process. Switch to streamable-http only when you want one long-lived local server that several clients connect to.
| stdio (default) | streamable-http | |
|---|---|---|
| Who starts mema | each client spawns a child process | you run one persistent process; clients connect to it |
| Background process needed | no | yes — otherwise it dies when the terminal closes |
| Client config | command + args | url + two fixed request headers |
| Good for | one person, one client | several clients on one machine sharing one memory store |
Setting it up:
mcp.transport to "streamable-http" in ~/.config/memory-arbiter/config.json (or MEMORY_ARBITER_MCP_TRANSPORT=streamable-http).examples/com.memory-arbiter.mema.plist runs it at load, restarts on crash, and logs to /tmp/mema.{out,err}.log (replace __MEMA_BIN__ with the absolute path which mema prints; put it in ~/Library/LaunchAgents/ then launchctl load). For a quick try, tmux new -d -s mema 'mema' works.examples/streamable-http.mcp.json, filling in X-Mema-Client and X-Mema-Agent-Id.Notes: HTTP request handling is stateless (a frozen constant since 0.15.0) because mema keeps memory and semantic-notice state in SQLite, not in an MCP session. A service restart therefore does not leave clients holding an expired server session. Semantic notices created asynchronously are claimed from SQLite and attached to a later successful tool response as before; only a worker job that has not yet persisted its notice can be interrupted by a process restart.
The client sends the fixed headers automatically on every HTTP MCP request — agents must not add identity to individual tool data, or it is rejected. Missing/empty/duplicate/conflicting identity fails closed (400), never falling back to defaults. The service binds to loopback only; these headers are provenance, not authentication. Because launchd does not inherit your shell PATH or expand ~, put absolute paths in ProgramArguments and for any GGUF model_path in config.json.
Claude's local MCP configuration launches stdio commands. To reuse one running mema HTTP service instead of spawning another mema process, put this single entry under mcpServers in ~/.claude.json (current Claude Desktop/Cowork and Claude Code installations may share this user-level file):
Use the absolute npx path from which npx on your machine. Remove any older memory-arbiter entry that directly launches mema/memory-arbiter-mcp, otherwise Claude may start a second server process. Fully quit and reopen Claude Desktop, and restart Claude Code sessions after changing the file. mcp-remote is a third-party bridge; the pinned version above is the configuration tested with mema. If your Claude installation uses a separate Desktop MCP file, place the same single entry there instead, but do not register both copies.
During development, package/docs may describe an unreleased dev version while server.json intentionally remains at the last published registry release (0.13.1). The registry manifest is advanced only as part of release preparation; do not treat that deliberate lag as the runtime/database upgrade matrix.
Memory Arbiter（迷码）是面向 AI Agent 的本地可信事实层：每条事实只存一份完整原文，向量与检索均为可重建的派生索引。冲突 scan 走宽门召回，write-time notice 走双向四字段 Qwen 抽槽与严格 grounding；单一 conflicts 表保存一对多事件，生命周期为 open → applying → resolved 或 not_a_conflict。裁决后按 judge → apply_conflict_action → resolve_conflict 顺序治理。none/weak/strict 都做 workspace 归一；strict 使用 guarded vector admission，default 池不进入项目 scope。workspace_state_v1 升级会清除旧 conflict/judgment/notice 历史和旧 workspace decision event ledger，并要求完成带 epoch 的全库 scan。完整中文文档见 README.zh-CN.md；另见 INTRO.md 与 docs/INTEGRATION.zh-CN.md。