用途
Memory Arbiter（迷码）是一个面向 AI 编程工具的共享记忆中间层。每个编码 Agent（如 Claude Code、Cursor、Codex、ZCode）通常各自记笔记、互不知晓，导致事实重复、互相矛盾并悄然过时。Memory Arbiter 用一个本地 SQLite 事实库替代这种分散状态：所有 Agent 读取同一份经过验证的事实，今天在 Claude 中做出的决定，明天在 Cursor 中仍然可用。
主要能力
- 定向检索：词法与句级证据通道并行搜索并按排名融合，官方称在发版考试中自召回为 65/65。低于阈值的候选不会出现在结果页，每条命中携带来源偏移，可用 read span=[start,end] 截取精确原文。
- 冲突仲裁：由自训练的本地 mDeBERTa 三分类判定器（无需提示工程、不挑选胜者）处理候选对。只有高置信冲突会通知用户，灰色地带作为低优先级参考展示，其余进入定时扫描。候选对经过确定性漏斗（句子预过滤 → 记忆筛选 → 余弦带 → 规则证据）后进入判定。判定器从不挑选胜者、从不编辑记忆；发现结果保存在可审计的 conflicts 生命周期（open → applying → resolved）中，由 Agent 在显式授权下处理（judge → apply_conflict_action → resolve_conflict，使用 CAS 固定修订）。
- 数据归属与安全：完整原文存放于用户机器上的单个 SQLite 文件，每次写入带出处，每次编辑带版本历史，并提供普通 / 受保护 / 锁定信任级别以及 user_confirmed 标签。默认不主动对外通信，唯一可选调用是 PyPI 更新检查（浏览器控制台会连接用户自行配置的 LLM 端点）。
- 知识库策展与工作台：本地浏览器控制台可挑选哪些记忆算作知识（kb_member 独立治理位，Agent 无法通过改写标签删除），按工作区 → 标签浏览并提供渲染后的 Markdown 与关系图；自带 LLM 的工作台支持六种一键学习动作：summarize / outline / quiz / Feynman / quiz-me / timeline，输出通过标准管道写回为记忆。
- 信任与隔离：每次写入带出处，版本历史仅追加；工作区隔离分为 none / weak / strict，strict 下新工作区保持待确认状态，保留的 default 池在项目范围内不可见。位于数据库旁的 recall_blacklist.jsonl 中列出的工作区会被排除在无范围检索之外，mema doctor 会报告生效列表。
使用方式
安装
可将以下方式交由具备终端权限的编码 Agent 执行，Agent 会把 README 作为事实来源，从环境中选择 uvx / core / vec / semantic-local 方案，无法安全推断时会停下来等待用户输入。安装成功的标志是已运行 mema doctor 并报告所有警告。手动安装为分步执行，然后参照 examples/*.mcp.json 接线 MCP 客户端，并用 mema 启动服务器。
首次使用须知
- 身份是显式的：在 config.json 中设置 client 与 agent_id，没有内置默认值，任一为空服务器会拒绝启动。
- remember 需要 workspace：先调用 memory_review(view="workspaces") 列出已有桶，再传入一个；'default' 是全局池。
- 每次调用返回 {ok, mode, warnings, degraded, data}；需要用户注意的事项以 notices 或 data.action_required 形式出现。可让任意 Agent 查看打包规则：memory(action="help", data={"topic":"agent_onboarding"})。
日常循环
四个调用构成日常循环：remember 记录可复用事实，find 用于回忆，read 用于精确查找，update 在新来源替换旧事实时使用（同一事实来源绝不保留第二个活动副本）。find 是指索引页（元数据 + content_chars + 带来源偏移的提纲）；batch_find 把 8 个查询合并为一次往返；read span=[start,end] 精确引用；空回忆会如实说明，而不是塞入最近的记忆。
配置
配置为纯文件形式，位于 ~/.config/memory-arbiter/config.json，完整配置面为 28 个键，模板见 examples/memory-arbiter.config.example.json，逐键文档与迁移表见 docs/INTEGRATION.md。首日重要的键：embedding.model_path（指向本地 GGUF 模型是启用证据回忆的唯一意图）、semantic_conflict.mdeberta_ckpt（指向判定器检查点即启用写入时仲裁）、mcp.transport（stdio 默认，或 streamable-http 用于共享本地服务器）。存在六个启动上下文环境变量（MEMORY_ARBITER_CONFIG / DB_PATH / BACKUP_JSONL / MCP_TRANSPORT / CLIENT / AGENT_ID），配置文件优先；其它 MEMORY_ARBITER_* 导出会警告“no longer read”。
HTTP 模式
stdio（默认）无需后台进程。要在多个客户端间共享一个服务器：将 mcp.transport 设为 "streamable-http"，保持进程存活（示例中有 launchd 模板，mema 无内置守护进程），并让客户端指向 http://127.0.0.1:8000/mcp，使用示例文件中的固定 X-Mema-Client / X-Mema-Agent-Id 头。仅限回环地址；头信息用于出处标识，不是认证。Claude Desktop / Claude Code 通过单条目 mcp-remote 桥接连接。
冲突判定模型（mDeBERTa，可选）
一次性手动安装：pip install memory-arbiter-mcp[mdeberta]；从 mini-clash 发布产物下载 mdeberta-v58_ep3_fp16.pt（约 531MB 的 fp16 检查点不在 PyPI 上发布）以及 mdeberta-base tokenizer 目录（来自 memarbiter.cn 的离线安装包已包含，可跳过此步）；将 semantic_conflict.mdeberta_ckpt 指向它，启动时自动启用并预加载，mema doctor 会验证摘要与标签契约。
从旧数据库升级
早于 schema 代 workspace_state_v1 的数据库会在启动时被拒绝，需运行并行的 mema upgrade（用 --dry-run 预览，源数据库不会被删除）。完整操作指南（WAL 安全备份、迁移与有意丢弃的内容、升级后的扫描纪元）见 docs/UPGRADE.md（中文版 docs/UPGRADE.zh-CN.md）。
适用场景
- 多个编码 Agent 并行工作，需要共享同一份事实与决策记录的团队或个人。
- 对数据本地性要求高、不希望记忆上传云端的开发场景。
- 需要为事实维护出处、版本历史与信任级别，防止已确认内容被静默改写的知识工作。
- 需要在本地策展知识库并借助自带 LLM 进行摘要、提纲、测验等学习操作的用户。
限制与注意事项
- 未配置 embedding：无 sqlite-vec / embedding 模型时，词法回忆与治理继续可用，但证据索引不可用。
- 未配置判定器：写入时仲裁暂停，定时扫描仍返回确定性候选。
- SQLite 不可用：写入回退到仅追加的 JSONL 信封；工作区决策状态需要数据库。
- 身份必须显式设置 client 与 agent_id，否则服务器拒绝启动。
- remember 必须指定 workspace，需先列出已有桶。
- HTTP 模式仅限回环地址，头信息不是认证机制。
- mDeBERTa 检查点（约 531MB fp16）不随 PyPI 包发布，需手动下载或使用离线安装包。
- 评测数据：官方称在 LoCoMo-Refined（全部 1,382 题，官方评判器 Qwen3-14B）上，Mem0 完整管道在同为纯文本口径下得 48.91%（由基准作者重新评分），裸 mema 在写入路径无 LLM 时与之持平；配合 writer-agent 时，mema 纯文本得分在榜单上仅次于 MemoraX。内部发版考试包含 42 条回忆查询（五类：paraphrase / lookup / legal / far / keyword）、108 对冲突（四类标签，其中 36 对真实冲突）与四组相似度标签组。以上为官方提供的资料，更多细节与复现方法见 evals/locomo/RESULTS.md 与 eval/runner.py --suite all。
- 部分定价、平台支持范围等具体信息暂未提供。
