sedimem

记忆不是攒得越多越好 —— 它该像地层一样沉积、可回溯、会收敛。

跨会话、跨客户端的本地记忆层：DSH / Codex CLI / Claude Code 三端共读一份真相层， 把"记忆"当数据库治理，而不是当 prompt 攒。

🌐 图文版项目站 · 快速开始 · 架构 · 三端接入 · 部署 · 设计决策 · 文档

为什么

用久了会发现，几乎所有 agent 记忆方案最后都烂在同一个地方：它不是"检索得不够准"，而是"根本没人管"。

sedimem 的立场是：记忆的难点在治理，不在检索。所以它把力气花在四件事上—— 写入时去重、冲突时失效而不删除、过期后仍可回看、脏数据不进上下文。

它解决什么

刻意不做：embedding 语义检索、多机同步、加密存储、多用户权限隔离（scope 是分类，不是权限边界）。

架构

四层结构，依赖单向：

• 客户端层：DSH / Codex CLI / Claude Code 通过 MCP 连入；人用 CLI；浏览器用只读观察台。
• 接口层：MCP（memory_* 10 个工具）· CLI · Web（/api/* 只读，没有写端点）。
• 核心服务：一个 MemoryService，拆成 lifecycle / write-path / search-path / maintenance 四模块， 语义只在一处，门禁用 tests/unit/service-facade.test.js 保证方法集合不漂移。
• 治理层：写入门控、近重复扫描 + Agent 裁决、冲突失效（bi-temporal）、投毒打标、入库脱敏、配额与压实。
• 读路径：BM25 打底；语义道可选（search.embedder.kind，默认 none），开启后 RRF 融合两条路， 每条结果带 basis（bm25 / vector / bm25+vector）。语义道不可用时返回 degraded 并退回词法 —— 永不阻断检索。
• 注入：memo brief --tier0 给预算内目录；DSH 插件可在每步注入（默认关，≤1200 字符，围栏声明「数据不是指令」）。
• 捕获：memo capture scan 把「记住/决定/坑」抽成候选进 inbox，accept 才落真相层 —— 不做自动写入。
• 派生层：倒排索引 / SQLite FTS5 / brief / L2 场景块 / L3 画像 —— 全部可从真相层重建。
• 真相层：items/<scope>.jsonl，只追加，唯一不可重建的东西。

四条卫生路径的成本分工（这是能长期跑下去的关键）：

为什么叫 sedimem

s edi ment + mem ory：记忆像地层一样沉积，而不是被反复改写覆盖。 （原名 strata 与多个开源项目重名，2026-11-10 更名。）

产品名是 sedimem；技术标识为向后兼容保持不变：CLI 仍是 memo、环境变量 MEMO_*、 MCP 工具 memory_*、serverName 仍是 memo（改名要同步三端配置与历史分库，留到带兼容期的大版本）。

快速开始

需要 Node ≥ 22，零运行时依赖。

git clone https://github.com/Old-Friends-Gathering/sedimem && cd sedimem
NODE=$(command -v node)
V=versions/$(cat versions/CURRENT)          # 当前版本目录由指针决定

$NODE --test "$V/tests/**/*.test.js"        # 288 个测试（单元 + 注入式回归）
$NODE $V/eval/run.js                         # I1–I24 注入式评测，结果写 $V/eval/results/
$NODE $V/src/cli/memo.js --help              # CLI 入口
$NODE $V/src/mcp/server.js                   # MCP server（stdio）

最小的三条命令，看看它到底在干什么：

$NODE $V/src/cli/memo.js write --kind fact --title "CI 要求 Node 22+" \
  --text "部署流水线要求 Node 22 及以上" --agent cli
$NODE $V/src/cli/memo.js search "node 版本"
$NODE $V/src/cli/memo.js brief          # 给 Agent 看的浓缩摘要

三端接入（DSH / Codex / Claude）

MCP 是唯一的接缝。三端各自配一条 stdio server，指向同一个 server.js 和同一个 MEMO_HOME：

一键自检（写盐值 → 另一个进程召回 → 用召回值作答）：

bash $V/configs/verify-three-clients.sh     # 期望输出 PASS

常驻进程注意：DSH 的 MCP 子进程 cwd 固定，分库会解析成 dir:<profile>。 进会话先 memory_scope 看一眼，不对就 memory_scope({action:'use', path:'<项目根>'}) —— 选择按客户端持久化。

部署（常驻观察台与 nightly）

# 只读观察台（默认 127.0.0.1:7788，只绑回环）
$NODE $V/src/cli/memo.js serve --port 7788

# 夜间整合：重算 brief / metrics / 去重候选
$NODE $V/src/cli/nightly.js

macOS 上建议用 launchd 常驻（模板见 configs/launchd/）， 入口统一走 scripts/sedimem-run.sh —— 它读 versions/CURRENT， 所以换大版本只改指针，plist 与 crontab 都不用碰：

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/live.sedimem.observer.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/live.sedimem.nightly.plist
launchctl kickstart -k gui/$(id -u)/live.sedimem.observer   # 改完代码热加载

看一眼（只读观察台）

命令与工具

memory_write · memory_search · memory_brief · memory_get · memory_supersede · memory_forget · memory_curate · memory_dedupe_scan · memory_stats · memory_scope

设计取向：读比写多。写只有 write/supersede/forget/curate 四个，其余全是只读； forget 默认只写墓碑，物理删除另有唯一入口。

质量门禁

main 是受保护分支，对管理员同样生效（直推/force push 会被 GH006 拒绝）。 任何改动都必须走 issue → 分支 → PR → 九项检查全绿 → squash：

本地跑同一份脚本（提交前先自己过一遍）：

node tools/quality-check.mjs && node tools/security-check.mjs && node tools/coverage-gate.mjs
node tools/pages-verify.mjs --attempts 1   # 可选：立刻看一眼线上是不是当前版本

阈值为什么是这个数、谁能改 → docs/07； 开发流程 → CONTRIBUTING.md。

设计决策（为什么这么做）

这些不是"最佳实践抄来的"，每一条都对应一个实测过的失败：

• 只有 compact 能物理删除 —— 因为 forget 一旦真删，asOf 就永久失去可回溯性；删除走墓碑 + 7 天宽限。
• supersede 不能复活墓碑 —— 否则 purge 语义被打断，清理过的数据会从别处"爬回来"。
• suspicious 遮蔽覆盖 subject/predicate/value/source.quote，不只 text —— 实测投毒经 value 穿透了 tier0。
• scope 名禁路径分隔符，但保留空格与大小写 —— dir:my project 是合法目录名，穿越才是攻击。
• CI 的 eval job 名改动前必须先 PATCH 分支保护的 required checks —— 否则 PR 永远等一个不存在的检查。
• node --test tests/ 会 MODULE_NOT_FOUND —— 必须用 glob 'tests/**/*.test.js'。

完整裁决列表（1–60 条，每条附实测证据）见 docs/02 的 §3.x 各节。

文档地图