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

memory-arbiter-mcp

中文 | English

English

A lightweight, fully local MCP Server that gives your AI coding tools a shared memory store with built-in conflict arbitration.

Every tool — ZCode, Codex, Cursor, Claude Code — has its own memory. They don't talk to each other. Memory Arbiter fixes this: one SQLite database, all tools read and write through the same MCP protocol, conflicts are resolved by structured rules (not LLM guesswork).

Why Memory Arbiter?

Most AI clients load their entire memory file (MEMORY.md + memory/*.md) into the system prompt every turn. As memory grows, so does your token bill — 5K–20K tokens of context burned before the model even reads your question. Memory Arbiter is a token-optimization middleware: precise retrieval replaces full-file loading.

Positioning, in four lines:

• ✅ Structured memory storage — SQLite + dual timeline + source trust levels
• ✅ Conflict arbitration engine — rule-based verdicts with explainable rationale
• ✅ Cross-tool sharing layer — one database, every AI client shares it
• ✅ Token-optimization middleware — precise retrieval replaces full-file loading
• ❌ Not an LLM, does not do semantic reasoning — semantic judgement stays with the AI client

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

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 (zcode, codex, cursor, claude-code). All tools share the same DB_PATH — that's the whole point.

⚠️ 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

MCP Tools

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

中文

一个轻量、完全本地运行的 MCP Server，给你的 AI 编程工具提供共享记忆库，内置冲突仲裁机制。

你同时用 ZCode、Codex、Cursor、Claude Code——每个工具都有各自的记忆，互不相通。Memory Arbiter 解决这个问题：一个 SQLite 数据库，所有工具通过同一个 MCP 协议读写，冲突由结构化规则仲裁，不依赖大模型。

为什么需要 Memory Arbiter？

多数 AI 客户端每轮对话都把整个记忆文件（MEMORY.md + memory/*.md）塞进 system prompt。记忆越多，token 消耗越大——模型还没读你的问题，5K–20K token 的上下文已经烧掉了。Memory Arbiter 是一层 token 优化中间件：用精准检索替代全文加载。

定位（四句话）：

• ✅ 结构化记忆存储 — SQLite + 双时间轴 + 来源可信度
• ✅ 冲突仲裁引擎 — 规则化裁决，输出可解释理由
• ✅ 跨工具共享层 — 一个数据库，所有 AI 客户端共享
• ✅ Token 优化中间件 — 精准检索替代全文加载
• ❌ 不是 LLM、不做语义推理 — 语义判断交给 AI 客户端

三种典型用法（每轮按需检索、定时审查、写入时冲突检测）和一个真实的跨工具委派案例见 docs/INTEGRATION.md。

核心能力

• 结构化写入：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 标识（zcode、codex、cursor、claude-code），共享同一个 DB_PATH——这就是跨工具记忆共享的关键。

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

客户端配置位置

MCP 工具

数据迁移

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

# 拷贝数据库
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