mcp-name: io.github.billy12151/memory-arbiter-mcp

memory-arbiter-mcp

中文 | English

English

A lightweight, fully local AI enhancement middleware — not another memory tool, but a layer that makes every AI client you already use noticeably smarter, by fixing the one thing they all get wrong: context quality.

From planning (OpenClaw) to design (OpenDesign) to code (ZCode, Codex, Cursor, Claude Code) — Memory Arbiter connects your entire AI toolchain through one shared SQLite database.

Why Memory Arbiter?

Your AI client loads MEMORY.md + memory/*.md into the system prompt every turn. As knowledge grows, 5K–20K tokens burn before the model even reads your question — and worse, the model drowns in noise, losing track of what's current, what's confirmed, and what's stale.

Memory Arbiter replaces this with a SQLite-backed search: only the relevant entries come back, everything else stays on disk.

The result isn't just cheaper — it's sharper. When the model receives precise, de-duplicated, trust-ranked context, the same model produces noticeably better output. Most AI execution errors aren't the model being dumb — they're the model acting on stale, contradictory, or diluted context. Fix the input, and your existing model jumps a level.

Works with one tool. Scales to many.

Better output quality (the real win)

Token savings are easy to measure. But the deeper, more impactful change is output quality — because Memory Arbiter fixes what the model sees before it even starts thinking.

Same model. Better context. Better output. This is the core value — everything else (token savings, cross-tool sharing, audit trails) flows from giving your AI clean, structured, de-conflicted context.

What does it actually enhance?

Memory Arbiter doesn't add new capabilities to your AI — it removes the blind spots that cap the capabilities it already has:

Model-agnostic. Whether you run GLM, Claude, GPT, or Gemini — the stronger the model, the more sensitive it is to context quality, and the bigger the uplift Memory Arbiter delivers.

Solo user: still worth it with one tool

Even if you only use Cursor, Claude Code, Codex, or ZCode — Memory Arbiter upgrades your memory from flat markdown to a queryable database:

Multi-tool collaboration (bonus)

Using two or more AI clients? All solo benefits apply to each tool, plus a shared memory layer:

Token savings at a glance

Positioning, in five lines:

• ✅ Execution quality booster — clean, de-conflicted context → fewer hallucinations, sharper results (this is the core value)
• ✅ Structured memory storage — SQLite + dual timeline + source trust levels
• ✅ Token-optimization middleware — precise retrieval replaces full-file loading
• ✅ Conflict arbitration engine — rule-based verdicts with explainable rationale
• ✅ Cross-tool sharing layer — one database, every AI client shares it (optional but powerful)
• ❌ Not an LLM, does not do semantic reasoning — semantic judgement stays with the AI client

Real-world example: full creative pipeline (plan → design → code)

The user runs a three-tool pipeline: OpenClaw (planning & specs) → OpenDesign (page & slide design) → ZCode (implementation). Memory Arbiter connects the entire chain.

• Old way: OpenClaw writes a spec to a file → OpenDesign reads it, designs something → screenshots/specs are handed to ZCode. Path sync, version drift, copy-paste at every handoff. Or the user repeats the context each time — information loss + wasted tokens.
• Memory Arbiter way: OpenClaw calls memory_write with the spec → OpenDesign calls memory_search("the project") and gets full context, produces designs, writes back design decisions → ZCode calls memory_search("the project") and receives both the spec and the design decisions in one query — zero file handoff across three tools.

A spec + design handoff that used to cost ~5000 tokens of repeated context loading now costs ~800 tokens via targeted memory_search. This very project ships its own release tasks this way — it dogfoods itself. Full step-by-step in docs/INTEGRATION.md.

See docs/INTEGRATION.md for three concrete usage patterns (per-turn retrieval, scheduled audit, write-time conflict check) and the full cross-tool delegation walkthrough.

The Bigger Picture

Intelligence is converging. Facts are the differentiator.

AI models are getting smarter in lockstep. GPT-4o, Claude 3.5, Gemini 1.5, Llama 3, GLM-5, DeepSeek — run a blind test and most people can't tell them apart. Reasoning, generation quality, multimodal understanding: the gaps that once separated generations are closing fast. Base intelligence is becoming a public good.

Two narratives dominate the industry: the "Data Moat" (companies compete on proprietary data) and the "Context" school (agents need good context to perform). Both are right — but both miss the competitive axis that matters most for agents:

When every agent is smart enough, the winner is the one that commands more verified facts.

This isn't about having data (a static asset). It's about factual command — the dynamic ability to retrieve, verify, connect, and act on the right information at the right time. An agent with precise, de-duplicated, trust-ranked context outperforms a "smarter" model drowning in noise — every time.

Memory Arbiter is the engineering answer to this principle. It doesn't make your model smarter. It makes your model better informed. Structured storage, conflict arbitration, trust levels, cross-tool sharing, semantic recall — every feature is designed around one thesis:

In the age of convergent intelligence, factual mastery is the ultimate competitive edge.

Features

• Structured memory write: content, agent_id, workspace, tags, source_type, event_time, ingest_time, confidence, protection_level, and more.
• Source trust levels: user_confirmed > document_extracted > agent_generated > unknown.
• Dual timeline arbitration: resolves conflicts by user confirmation → event time → source trust → ingest time. Every decision comes with an explainable rationale.
• Locked protection: user_confirmed memories are automatically locked — no agent can overwrite them.
• Client policy system: per-client enable/disable, agent allow/deny lists for multi-agent governance.
• Graceful degradation: sqlite-vec → FTS5 → LIKE → JSONL backup. Never crashes.
• Zero cloud, zero LLM calls: pure local SQLite. No Postgres, Redis, or external services.

Quick Start

Requirements: Python 3.11+

# Clone
git clone https://github.com/billy12151/memory-arbiter-mcp.git
cd memory-arbiter-mcp

# Setup
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

# Optional: semantic recall via sqlite-vec
pip install '.[vec]'

# Run
memory-arbiter-mcp

Connect Your Tool

Add to your tool's MCP config (see examples/ for ready-made templates):

{
  "mcpServers": {
    "memory-arbiter": {
      "command": "/path/to/memory-arbiter-mcp/.venv/bin/memory-arbiter-mcp",
      "env": {
        "MEMORY_ARBITER_CLIENT": "zcode",
        "MEMORY_ARBITER_AGENT_ID": "zcode-default",
        "MEMORY_ARBITER_DB_PATH": "~/.local/share/memory-arbiter/memory.sqlite3"
      }
    }
  }
}

Change MEMORY_ARBITER_CLIENT for each tool (openclaw, zcode, codex, cursor, claude-code). Point multiple tools at the same DB_PATH to enable cross-tool memory sharing. (GUI tools like OpenDesign inherit the host CLI's config — no separate client name.)

⚠️ New session required: MCP servers are loaded at session startup. Already-open sessions won't see the new tools. Start a fresh session after configuring.

Client Config Locations

OpenDesign / OpenClaw GUI tools: these run on top of a host CLI (Codex CLI, Claude Code, etc.) and do not have their own MCP config entry. Whatever MCP server the host client has loaded is automatically available — e.g. once Codex CLI configures Memory Arbiter, OpenDesign running on top of Codex can call memory_search / memory_write natively with no extra setup.

MCP Tools

Optional: Semantic Recall (v0.5.0)

By default, memory-arbiter uses lexical recall (FTS5 trigram + BM25 + soft-rerank) — no embedding model, no heavy dependencies, fully local. This is enough for most cases.

For queries where wording differs but meaning is the same ("happy" vs "joyful", "金营平台" vs "金融带货"), you can opt into semantic recall. memory-arbiter does not bundle an embedding model — you bring your own, so the default install stays lightweight and you keep full control over the model, language, and cost. When configured, normal memory_write and memory_search(query="...") calls auto-embed; callers do not need to pass query_embedding manually.

Setup (4 steps):

1. Install sqlite-vec and the GGUF runtime:

   pip install memory-arbiter-mcp[vec]
   pip install llama-cpp-python
   

2. Choose an embedding model. For automatic embedding in v0.5.0, the built-in runtime supports local GGUF models:

   • GGUF (local, recommended) — works with any GGUF embedding model via llama-cpp-python. Reuses models you may already have (e.g. from OpenClaw/llama.cpp). Point the script at the file: embeddinggemma-300m-qat-Q8_0.gguf is a good 768-dim default.
   • sentence-transformers (local) — HuggingFace PyTorch models (bge-small-zh, bge-base-en, etc.): use your own backfill/query script and pass vectors to memory_store_embedding / memory_search(query_embedding=...).
   • Remote API (OpenAI / Zhipu / Tongyi) — call the API in your own backfill script, pass vectors to memory_store_embedding. memory-arbiter only needs pip install memory-arbiter-mcp[vec]; no model runtime on this side.

   Embedding Model Quick Reference (pick one, then match MEMORY_ARBITER_VEC_DIM to its dimension):

   Path	Recommended model	Dim	Source	Best for
   GGUF (local)	embeddinggemma-300m-qat-Q8_0.gguf	768	HuggingFace	Reusing a model you already have; no Python ML stack
   sentence-transformers	BAAI/bge-small-zh-v1.5 (CN) / bge-base-en-v1.5 (EN)	512 / 768	HuggingFace	Best quality-to-size ratio; needs PyTorch
   Remote API	text-embedding-3-small (OpenAI) / embedding-3 (Zhipu)	1536 / 1024	Provider dashboard	No local compute; per-call cost

   End-to-end flow for auto-embedding: pick GGUF model → put vec/model settings in ~/.config/memory-arbiter/config.json → restart the MCP server → run docs/semantic_example.py once to backfill old memories. New writes and plain-text searches auto-embed after that.

3. Copy the config template and edit paths:

   mkdir -p ~/.config/memory-arbiter
   cp examples/memory-arbiter.config.example.json ~/.config/memory-arbiter/config.json
   

   Keep vector/model settings here instead of each MCP client's env block. ~/.config/memory-arbiter/ is user-owned XDG config, so pip installs and client reinstallers do not overwrite it. The first auto-embedding call lazily loads the model and may be noticeably slower; later calls reuse it.

4. Backfill embeddings into existing memories, then search normally:

   python docs/semantic_example.py                 # backfill all active memories
   python docs/semantic_example.py --query "金营平台营销"   # try a semantic search
   

After configuration, normal memory_search(query="...") can generate the query vector automatically. Explicit query_embedding still works and takes precedence.

How it ranks: semantic candidates get a floor score just below content matches — they beat content-only noise but never outrank a real subject/tags hit. The arbitration and trust layer is untouched.

Measured impact (small sample, not a formal benchmark): on the same 15 golden queries + 18 pairwise constraints used to validate v0.3.0, enabling semantic recall improved Top-3 hit rate and pairwise ordering. The biggest win was pairwise pass rate reaching 100% — every "should-rank-above" constraint held. SQLite-side latency overhead was ~8ms per query; local embedding generation depends on your model/runtime.

Configuration

Configuration can come from MEMORY_ARBITER_CONFIG, then ~/.config/memory-arbiter/config.json, then environment variables/defaults. Put durable vector/model settings in the config file so they survive MCP client reinstall/migration. Environment variables remain useful for simple client identity and CI overrides. The full table with explanations is in docs/INTEGRATION.md.

Data Migration

Moving to a new machine? Just copy the SQLite file:

# Copy the database
cp ~/.local/share/memory-arbiter/memory.sqlite3 /new/machine/~/.local/share/memory-arbiter/

# Reinstall the project (don't copy .venv — rebuild it)
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e .

Testing

python3.11 -m pip install -r requirements.txt
python3.11 -m pytest

License

MIT

中文

一个轻量、完全本地运行的 AI 增强中间件——不是又一个记忆工具，而是一层让你正在用的每个 AI 客户端都明显变聪明的底层设施，修的是所有 AI 模型的共同短板：上下文质量。

从规划（OpenClaw）到设计（OpenDesign）到编码（ZCode、Codex、Cursor、Claude Code）——memory-arbiter 通过一个共享的 SQLite 数据库串起你的整条 AI 工具链。

为什么需要 Memory Arbiter？

你的 AI 客户端每轮对话都把 MEMORY.md + memory/*.md 整个塞进 system prompt。记忆越多，token 消耗越大——模型还没读你的问题，5K–20K token 的上下文已经烧掉了。更要命的是，模型淹没在噪声里，分不清什么是最新的、什么是用户确认的、什么是过时的。

Memory Arbiter 用 SQLite 检索替代全文加载：只有相关的条目返回，其余的留在磁盘上。

结果不只是更省钱——而是更准。 当模型拿到的上下文是精准的、去重的、按可信度排序的，同一个模型，输出质量会明显跃升。AI 执行出错，大部分时候不是模型笨，而是它拿到的输入是过时的、自相矛盾的、或者关键信息被噪声淹没了。修好输入端，你现有的模型直接提升一个等级。

一个工具就能用。多个工具更香。

输出质量提升（核心价值）

省 token 好量化。但更深层、更关键的改动是输出质量——因为 Memory Arbiter 修的是模型在开始思考之前看到的东西。

同一个模型，上下文对了，输出就准了。 这是核心价值——其他一切（省 token、跨工具共享、审计追溯）都是“给 AI 干净、结构化、无冲突的上下文”自然带来的结果。

它到底增强了什么？

memory-arbiter 没有给你的 AI 加新能力——它移除了卡住现有能力上限的盲区：

模型无关。 不管你用 GLM、Claude、GPT 还是 Gemini——模型越强，对上下文质量越敏感，memory-arbiter 带来的提升越大。

单客户端用户：只用一个工具也值得

即使你只用 Cursor、Claude Code、Codex 或 ZCode，Memory Arbiter 也能把你的记忆从扁平 markdown 升级成可查询的数据库：

多客户端协作（进阶收益）

同时用两个或更多 AI 工具？单客户端的所有收益 每个工具都享受，再加一层共享记忆：

Token 节省一览

定位（五句话）：

• ✅ 执行质量放大器 — 干净、无冲突的上下文 → 更少幻觉、更准的结果（核心价值）
• ✅ 结构化记忆存储 — SQLite + 双时间轴 + 来源可信度
• ✅ Token 优化中间件 — 精准检索替代全文加载
• ✅ 冲突仲裁引擎 — 规则化裁决，输出可解释理由
• ✅ 跨工具共享层 — 一个数据库，所有 AI 客户端共享（可选，但用了就回不去）
• ❌ 不是 LLM、不做语义推理 — 语义判断交给 AI 客户端

真实案例：完整创意管线（规划 → 设计 → 编码）

用户跑的是三工具管线：OpenClaw（规划 & 规格）→ OpenDesign（页面 & PPT 设计）→ ZCode（代码实现）。memory-arbiter 串起整条链路。

• 传统方式：OpenClaw 把规格写成文件 → OpenDesign 读文件做设计 → 设计稿和规格再交给 ZCode，每次交接都要约定路径、手动同步、版本混乱；或者用户每次重复描述背景，信息损耗大、token 浪费多。
• memory-arbiter 方式：OpenClaw 调 memory_write 写入规格 → OpenDesign 调 memory_search("项目") 拿到完整上下文，做设计，把设计决策写回 → ZCode 调 memory_search("项目") 一次拿到规格和设计决策——三个工具之间零文件传递。

一份规格 + 设计交接：传统重复加载上下文约 ~5000 tokens，现在精准检索约 ~800 tokens。 这个项目自己的发版任务就是这么跑的——用自己的产品喂自己的产品。完整步骤见 docs/INTEGRATION.md。

三种典型用法（每轮按需检索、定时审查、写入时冲突检测）和完整的跨工具委派步骤见 docs/INTEGRATION.md。

更大的图景

智能趋于平权，数据定义高下。

AI 模型的能力正在同步收敛。GPT-4o、Claude 3.5、Gemini 1.5、Llama 3、GLM-5、DeepSeek——做盲测，普通人已经分不清谁是谁了。推理、生成、多模态理解，曾经拉开代差的维度正以肉眼可见的速度缩小。基础智能正在变成公共品。

行业里两派主流叙事："Data Moat"（企业靠独占数据竞争）和 "Context"（Agent 需要好的上下文）。都对，但都没触及 Agent 竞争的最关键维度：

当所有 Agent 都足够聪明时，胜者属于掌握更多已验证事实的那个。

这不是"拥有数据"（静态资产），而是事实掌控力——在正确的时间检索、验证、关联、调用正确信息的动态能力。一个拿着精准、去重、可信度排序的上下文的 Agent，每次都能击败淹没在噪声里的"更聪明"的模型。

Memory Arbiter 就是这条原则的工程实现。 它不会让你的模型更聪明，但它会让你的模型更知情。结构化存储、冲突仲裁、可信度分层、跨工具共享、语义检索——每一个能力都围绕一个论点设计：

在智能趋同的时代，事实掌控力是终极竞争力。

核心能力

• 结构化写入：content、agent_id、workspace、tags、source_type、event_time、ingest_time、confidence、protection_level 等。
• 来源可信度：user_confirmed > document_extracted > agent_generated > unknown。
• 双时间轴仲裁：按 用户确认 → 事件发生时间 → 来源可信度 → 录入时间 的优先级判定，输出可解释的裁决理由。
• 锁定保护：user_confirmed 的记忆自动锁定，任何 Agent 都不能自动覆盖。
• 客户端策略：按客户端启用/禁用，Agent 级别的 allow/deny 白名单控制。
• 逐级降级：sqlite-vec → FTS5 → LIKE → JSONL 备份，不会崩。
• 零云依赖、零大模型调用：纯本地 SQLite，不需要 Postgres、Redis 或外部服务。

快速开始

要求：Python 3.11+

# 克隆
git clone https://github.com/billy12151/memory-arbiter-mcp.git
cd memory-arbiter-mcp

# 安装
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

# 可选：启用语义召回增强（sqlite-vec）
pip install '.[vec]'

# 启动
memory-arbiter-mcp

接入工具

在你的工具的 MCP 配置中加入（完整示例见 examples/ 目录）：

{
  "mcpServers": {
    "memory-arbiter": {
      "command": "/path/to/memory-arbiter-mcp/.venv/bin/memory-arbiter-mcp",
      "env": {
        "MEMORY_ARBITER_CLIENT": "zcode",
        "MEMORY_ARBITER_AGENT_ID": "zcode-default",
        "MEMORY_ARBITER_DB_PATH": "~/.local/share/memory-arbiter/memory.sqlite3"
      }
    }
  }
}

每个工具改一下 MEMORY_ARBITER_CLIENT 标识（openclaw、zcode、codex、cursor、claude-code）。多个工具指向同一个 DB_PATH 即可启用跨工具记忆共享。（OpenDesign 这类 GUI 工具继承宿主 CLI 的配置，不需要单独的 client 名称。）

⚠️ 需要新建会话：MCP Server 在客户端启动时加载，已经打开的会话不会识别新添加的 Server。配置好后请新建一个会话。

客户端配置位置

OpenDesign / OpenClaw GUI 类工具：这类工具寄宿在底层 CLI（Codex CLI、Claude Code 等）之上，没有自己的 MCP 配置入口。宿主客户端加载了哪个 MCP Server，GUI 工具就天然能用——例如 Codex CLI 配好了 memory-arbiter，跑在 Codex 上的 OpenDesign 就能直接调用 memory_search / memory_write，无需额外设置。

MCP 工具

可选：语义检索（v0.5.0）

默认情况下，memory-arbiter 用的是字面检索（FTS5 trigram + BM25 + 软重排）——不依赖 embedding 模型、不引入重依赖、完全本地。绝大多数场景这就够了。

对于"措辞不同但语义相同"的查询（比如搜"快乐"想命中"开心"、搜"金融带货"想命中"金营平台"），你可以可选开启语义检索。memory-arbiter 不内置 embedding 模型——你自己带模型，这样默认安装保持轻量，模型选择、语言、成本完全由你掌控。配置完成后，普通 memory_write 和 memory_search(query="...") 会自动向量化，调用方不用手动传 query_embedding。

四步开启：

1. 安装 sqlite-vec 和 GGUF 运行时：

   pip install memory-arbiter-mcp[vec]
   pip install llama-cpp-python
   

2. 选一个 embedding 模型。v0.5.0 的自动向量化内置支持本地 GGUF：

   • GGUF（本地，推荐）——通过 llama-cpp-python 跑任意 GGUF embedding 模型。能复用你已有的模型（比如 OpenClaw/llama.cpp 用的）。把脚本指到模型文件： embeddinggemma-300m-qat-Q8_0.gguf 是一个 768 维的默认选择。
   • sentence-transformers（本地）——HuggingFace PyTorch 模型（bge-small-zh、bge-base-en 等）： 用你自己的 backfill/query 脚本，把向量传给 memory_store_embedding / memory_search(query_embedding=...)。
   • 远程 API（OpenAI / 智谱 / 通义）——在你自己的灌向量脚本里调 API，把向量传给 memory_store_embedding。memory-arbiter 这侧只需 pip install memory-arbiter-mcp[vec]，不跑任何模型。

   向量模型速查表（任选一个，然后把 MEMORY_ARBITER_VEC_DIM 设成它的维度）：

   方式	推荐模型	维度	来源	适用场景
   GGUF（本地）	embeddinggemma-300m-qat-Q8_0.gguf	768	HuggingFace	复用已有模型；不想搭 Python ML 环境
   sentence-transformers	BAAI/bge-small-zh-v1.5（中）/ bge-base-en-v1.5（英）	512 / 768	HuggingFace	性价比最高；需要 PyTorch
   远程 API	text-embedding-3-small（OpenAI）/ embedding-3（智谱）	1536 / 1024	各平台控制台	不想本地算力；按调用计费

   自动向量化完整流程一句话：选 GGUF 模型 → 把 vec/model 配置写到 ~/.config/memory-arbiter/config.json → 重启 MCP server → 跑一次 docs/semantic_example.py 给旧记忆补向量。之后新写入和普通文本查询会自动向量化。

3. 复制配置模板并修改路径：

   mkdir -p ~/.config/memory-arbiter
   cp examples/memory-arbiter.config.example.json ~/.config/memory-arbiter/config.json
   

   向量和模型配置建议放这里，不放每个 MCP 客户端的 env 段。~/.config/memory-arbiter/ 是用户自己的 XDG 配置目录，pip 安装和客户端重装不会覆盖。第一次自动向量化会懒加载模型，可能明显慢一次；后续复用已加载模型。

4. 给现有记忆补向量，然后正常搜索：

   python docs/semantic_example.py                 # 给所有活跃记忆补向量
   python docs/semantic_example.py --query "金营平台营销"   # 试一次语义检索
   

配置完成后，普通 memory_search(query="...") 可以自动生成查询向量。显式 query_embedding 仍然支持，并且优先级更高。

排序规则：语义召回的候选会给一个保底分（略低于正文命中分）——它能压过"正文顺带提及"的噪音，但永远不会盖过真正的标题/标签命中。仲裁和可信度分层逻辑完全不动。

实测效果（小样本，非正式 benchmark）：在 v0.3.0 验证用的同一套 15 条黄金查询 + 18 条 pairwise 约束上，开启语义检索后 Top-3 命中率和排序质量进一步提升。最大的亮点是 pairwise 通过率冲到 100%——所有"该排前面的都排在前面了"。SQLite 侧查询延迟约多 8ms；本地 embedding 生成耗时取决于模型和运行时。

配置

配置读取顺序：MEMORY_ARBITER_CONFIG 指定文件 → ~/.config/memory-arbiter/config.json → 环境变量/default。耐久的向量和模型配置建议放配置文件，避免 MCP 客户端重装/迁移时丢失；环境变量仍适合简单 client 标识和 CI 覆盖。完整说明见 docs/INTEGRATION.md。

数据迁移

换电脑只需拷贝一个文件：

# 拷贝数据库
cp ~/.local/share/memory-arbiter/memory.sqlite3 新电脑:~/.local/share/memory-arbiter/

# 重新安装项目（.venv 不要拷贝，新机器上重建）
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e .

测试

python3.11 -m pip install -r requirements.txt
python3.11 -m pytest

License

MIT