memtether

MemTether — AI 记忆法庭

你的 Agent 会记住事情。谁来审查它记住了什么？

MemTether 是面向多客户端 AI Agent 的本地优先记忆中心。大多数 记忆系统都在比拼检索准确率，而 MemTether 比拼的是 治理：谁写入了每条事实、何时生效、取代了什么、哪些冲突由 人工裁定，以及任何人都能验证的防篡改哈希链——无需代码， 无需依赖项。它也提供检索功能（SGM 确定性 SQL 路由 + 混合嵌入）， 但这不是重点：让 Agent 记忆能够被审计、纠正并值得信赖， 才是核心。

正在从 mem0、Zep 或 Letta 迁移？examples/mem0_migration.py 展示了从 mem0 JSON 导出文件进行完整往返迁移的过程——无需 mem0 SDK。

$ memtether court fact-20261007-abc
+============================================================+
| MEMTETHER MEMORY COURT - CASE FILE                          |
| 1. CONTENT    Clash proxy port is 7897                      |
| 2. TEMPORAL   valid: 10-05 → present | known: 10-05 → now   |
| 3. PROVENANCE #1 remember by=codex → #2 correct by=user     |
| 4. CONFLICTS  case #3: vs fact-...old verdict=superseded    |
| 5. INTEGRITY  chain: PASS (3 anchors, 42 entries hashed)    |
+============================================================+

简介

• 你的 AI 客户端彼此无法共享记忆？ 每个 Agent 都保留自己的记忆。MemTether 通过文件级指针为它们提供一个共享且受治理的大脑——无需云服务，也无需同步。
• 你的 AI 写入了不该写入的内容？ 每条记忆都带有来源身份和哈希链审计记录。篡改数据库，哈希链就会检测出来——运行 python examples/audit_chain_demo.py，看看它如何变红。
• 你的 AI 改变了主意？ 更正绝不会删除内容。双时态取代机制会永久保留谁在何时因何原因更改了什么，并且可以查询任意过去时间点的数据。

自行运行：

$ python examples/audit_chain_demo.py
写入 25 条记忆（自动生成 2 个审计锚点）...
篡改前 verify_chain: PASS {'anchors': 2, 'entries_covered': 20}
模拟攻击者直接改库...
篡改后 verify_chain: FAIL {'reason': 'chain hash mismatch'}
✅ 哈希链成功检测到篡改！

> Note: ntries_covered: 20 with 25 writes is expected — the hash chain anchors every 10 audit entries, so the last 5 writes sit in the unanchored tail until the next batch. Tampering with an *anchored* entry is what turns verification red.

从 mem0 迁移

已经在使用 mem0？examples/mem0_migration.py 展示了完整的往返流程：mem0 JSON 导出 → MemTether Exchange v1 → 实时检索 → 转回 mem0 格式。无需 mem0 SDK，双时态 字段会如实标记为 temporal_source="backfilled"。

性能（微基准测试，n=200，本地 SQLite）

操作	p50	p95	p99
记忆写入（插入）	28.7ms	34.6ms	117.8ms
搜索（SGM 实体）	33.1ms	39.5ms	41.6ms
搜索（关键词）	32.2ms	35.0ms	135.0ms
更正（取代）	50.8ms	54.7ms	54.7ms

复现：python _dev/benchmarks/bench_latency.py --n 200

文档

其底层机制包括：取代链（更正绝不删除）、 双时态时间戳（事实何时为真，以及系统何时得知这些事实）、 人工裁定的冲突解决机制，以及一份哈希链审计日志，其设计考虑了 《欧盟 AI 法案》第 12 条的记录保存要求（并非经认证的合规方案） 记录保存要求。

一个实体 SQLite 数据库，通过文件级指针供每个 AI 客户端共享。 没有云服务，没有 API 费用，没有同步守护进程。可搜索、可纳入 Git、归你所有——并且可审计。

与 mem0（66.6K★）、Zep/Graphiti（31.5K★）和 agentmemory（29.2K★）相比： 这些系统要么覆盖，要么删除旧值。MemTether 的取代 链会保留完整历史，并标注来源和 Q-Value 排名。 EAF 检索：在 LongMemEval 500Q 上严格准确率为 75.7%（配对差值 +19.4pp，McNemar p=7.8e-7）。

MemTether 对比

	MemTether	memora (731★)	memtrace (486★)	icarus (290★)	mem0 (66K★)
取代链（更正不会删除）	✅ 强制执行	❌	❌	✅	❌ 覆盖
证据链（防篡改，可通过浏览器验证）	✅ court CLI + zip	❌	❌	❌	❌
人工冲突裁定（记录决策）	✅ conflicts CLI	❌	❌	❌	❌
双时态（valid_from ≠ recorded_at）	✅ 覆盖 100% 的事实行	❌	✅ 用于知识图谱边（不适用于单条事实行）	❌	❌
来源归属（记录由谁撰写，并强制执行）	✅ 注册表 + 拒绝	❌	❌	✅ 来源追溯	❌
双时态（单条事实行）	✅	❌	❌	❌	✅ 仅图谱边
冲突检测（基于规则 + 人工审核）	✅ 候选生成器	❌	❌	❌	❌
MCP 服务	✅	✅	✅	❌	✅
23+ 个客户端适配器	✅ 自动检测	❌	❌	❌	❌
评估完整性框架	✅ 5 种模式	❌	❌	❌	❌
CI：9 个任务 / 567 项测试	✅	?	?	?	✅
语言	Python	?	Rust	?	Python

“每个单元格反映了截至 2026-10-07，该功能是否出现在项目的公开文档中。MemTether 的差异化优势不在于任何单一功能，而在于将所有治理维度整合到一个本地优先的部署中。”

产物包，包含每个问题的记录。

mcp-name: io.github.lanbass869-cell/memtether

项目页面 · 安装 · 文档 · 复现 · 中文文档

安装 · 使用方法 · 为什么选择 MemTether · 基准测试 · 架构 · 安全 · 常见问题

• 复现 MemTether - 每项声明都有对应命令
• 创始 10 人挑战 - 10 个名额，14 天，诚实呈现结果
• 文档（中文） - 用中文复现 / 参与挑战

快速开始

pip install memtether -i https://pypi.org/simple/
memtether init    # creates DB + connects all detected AI clients

就这么简单。MemTether 会检测你机器上的 Claude Code、Cursor、Windsurf、Codex、Gemini CLI 和另外 18 个客户端，写入 MCP 配置并进行验证。

中国用户：如果 pip install memtether 因 No matching distribution 而失败，清华镜像可能落后于 PyPI。请使用：pip install memtether -i https://pypi.org/simple/

# One client at a time
memtether setup claude-code
memtether setup cursor
memtether setup gemini-cli    # run `memtether setup list` for all 23

# With semantic search (local embedding, no cloud):
pip install "memtether[vector]"          # 1. deps (chromadb, onnxruntime)
memtether download-models                # 2. weights (bge-m3-int8 ~560MB, or --profile bge-small-zh ~46MB)
python -m memsearch --rebuild            # 3. build the vector index
# Skip any of these and search gracefully degrades to keyword + BM25.

# With REST API server + web dashboard
pip install "memtether[server]"
memtether dashboard

# Docker
docker-compose up

> **Security note**: the REST API is unauthenticated unless you set MEMTETHER_API_KEY. Only expose port 8080 to trusted networks — on a shared machine, set the key in .env before docker-compose up.
> **`memtether init` caveat**: auto-detection works for clients in standard install paths. Clients in custom locations may be missed or falsely reported — use `memtether connect verify` to confirm, and see docs/ADAPTERS.md for manual MCP config.

为什么选择 MemTether

其他记忆系统都做不到的一点：更正不会删除

# Monday: Claude Code writes
$ memtether remember "Deploy to port 8080" --source claude-code

# Wednesday: you correct it via Cursor
$ memtether correct fact-xxx "Deploy to port 9090" --reason "port changed"

# Friday: another agent searches
$ memtether search "deploy port" --list
  1. [fact] Deploy to port 9090 (active)          ← current truth
     Old "port 8080" is superseded, not deleted.
     Full chain: memtether timeline fact-xxx

每条记忆都有 valid_from / valid_to（业务时间）以及 recorded_at / invalidated_at（系统时间）。你可以查询“系统在星期二时知道什么？”

差异

架构

Claude Code ────┐                  ┌──── Cursor
                │   symlink /      │
Codex ──────────┤   junction       ├──── Windsurf
                │                  │
Gemini CLI ─────┤                  ├─── WorkBuddy
                └───────┬──────────┘
                        │
                        ▼
              ┌──────────────────┐
              │   memory.db      │  ← One physical SQLite
              │   (WAL mode)     │
              ├──────────────────┤
              │ FTS5 trigram     │  ← BM25 full-text
              │ ChromaDB + bge-m3│  ← Semantic (optional)
              │ RRF fusion       │  ← Multi-path merge
              │ 4-factor rerank  │  ← Z-score + sigmoid
              │ Supersession     │  ← Never delete
              │ Bi-temporal      │  ← T-axis + T'-axis
              │ Q-Value          │  ← Usage-based ranking
              │ Hubguard         │  ← Concurrent write lock
              │ Poisoning guard  │  ← OWASP LLM defense
              └──────────────────┘

连接你的客户端

# All detected clients (recommended)
memtether init

# One at a time
memtether setup claude-code
memtether setup cursor
memtether setup windsurf
memtether setup codex

支持的客户端（23 个）： Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、Zed、JetBrains、Cline、Roo Code、Kilo Code、Continue、Cody、Amazon Q、Gemini CLI、Neovim、Codex CLI、WorkBuddy（中国版 + 国际版）、CodeBuddy、ZCode、DSH、OpenClaw、Agents-Neutral

记忆操作

memtether remember "User prefers dark theme" --source claude-code
memtether search "theme" --layer L0    # First sentence only
memtether search "theme" --layer L1    # First 3 sentences
memtether search "theme"               # Full content (L2, default)
memtether profile --subject user       # What we know about this user
memtether correct <uid> "Updated"      # Supersede, never delete
memtether retire <uid> --reason "..."  # Retire (content preserved)
memtether provenance <uid>             # Full audit trail for one fact
memtether conflicts --stats            # Review conflict candidates
memtether court --verify               # Verify the audit hash chain
memtether stats
memtether export-md --out ./backup     # Export as markdown
memtether backup                       # Point-in-time DB backup
memtether reconcile --dry-run          # SQLite <-> vector drift report
memtether import-docs ./docs           # Cold-start from a directory
memtether remember-batch mems.json     # Batch write from JSON
memtether demo                         # Generate a synthetic demo DB (no real data)
memtether dashboard                    # Web UI

运行 memtether --help 查看完整列表（20 个子命令）。

也可以通过 MCP 执行相同的操作——你的 AI Agent 可以直接治理记忆：

# Via MCP: correct_memory / retire_memory / pin_memory / as_of_query / timeline / profile
# Your agent calls these tools — no CLI needed:

# Agent corrects a fact (supersedes old, creates new)
→ correct_memory(old_uid="fact-xxx", new_content="Deploy to 9090", reason="port changed")

# Agent queries what the system knew last Tuesday
→ as_of_query(at="2026-10-15", kind="known")

# Agent walks the full audit chain
→ timeline(uid="fact-xxx")

# Agent asks "what do we already know about this user?"
→ profile(subject="user")          # deterministic, no LLM, fully traceable

也可以通过 MCP 使用相同的操作（correct_memory、retire_memory、 pin_memory、as_of_query、timeline、profile）——Agent 无需使用 CLI 即可治理记忆。

分层召回（L0 / L1 / L2）

每次搜索都可以用三个深度返回同一条命中结果，因此 Agent 可以先快速扫描低成本的 单行摘要，仅对真正需要的命中结果获取全文：

memtether search "deploy port" --layer L0   # first sentence only (~1 line)
memtether search "deploy port" --layer L1   # first 3 sentences
memtether search "deploy port"              # L2 = full text (default)

在包含 2,200 条事实的生产数据库上测得（limit=5）：L0 的字符数仅为 L2 的 10%， L1 为 44%。这种拆分完全由确定性函数实现——不调用大模型，不产生幻觉，而且 L2 与分层之前的行为逐字节一致。

确定性用户档案

memtether profile --subject user           # human-readable
memtether profile --subject user --json    # machine-readable

汇总关于某个主体的所有已知信息（按类型/来源统计数量、时间跨度、高置信度事实，以及 可直接粘贴到系统提示词中的 L0 摘要）。 与 supermemory 的 get_profile 或 honcho 的 get_representation 不同，此功能 完全不调用大模型——相同的数据库始终生成相同的档案，而且每一行都能追溯到一个 uid。

memtether export-md --out ./backup     # Export as markdown
memtether dashboard                    # Web UI

基准测试

安全性

• 投毒防御：memtether_guard 可检测提示词注入、代码执行和敏感信息（OWASP LLM01/02/06），共 12 条规则
• 输入验证：内容 ≤10K、类型白名单、来源格式、置信度范围、范围白名单
• 范围隔离：shared / private / restricted
• 并发：Hubguard 文件锁 + 原子写入（WAL 模式）
• SQL：所有查询均使用参数化方式。没有 f-string SQL

为什么不直接使用 Markdown 文件？

Agent 很适合使用 Markdown，而 memtether export-md 可以为你生成 Markdown。但 原始 Markdown 文件无法回答“是谁写的、何时有效、它替代了什么？”——也 无法强制执行来源归属或检测篡改。

可随时导出为 Markdown — 但应将受治理的数据库保留为事实来源。

已知限制

1. 对于同一来源但路径不同的配置，tether_connect detect 可能会误报“未连接”
2. DSH 深度自定义（cordis.patch.yml）无法安全重写 — 使用 plan 预览
3. 语义搜索需要可选依赖（chromadb、onnxruntime）— 未安装这些依赖时会降级为关键词搜索
4. 优先支持 Windows。macOS/Linux 应该也能运行，但尚未充分测试
5. mem0/zep 的交换适配器仍处于实验阶段 — 需要安装相应的库

REST API

memtether dashboard   # starts server + opens browser
# or: uvicorn api_server:app --port 8820

14 个端点：/ /health /remember /search /stats /correct /retire /list /timeline/{uid} /absorb /qvalue /dashboard /court/verify /court/{uid}

贡献

请参阅 CONTRIBUTING.md。

许可证

Apache-2.0

如果 MemTether 对你有帮助，请在 GitHub 上给它点个 ⭐ — 这能帮助其他 Agent 发现它。

故障排除

路线图

请参阅 ROADMAP.md，了解计划中的工作和明确的非目标。