Shared Memory Layer — 多 agent 共享记忆 + 归纳

一个自托管的多 agent 共享记忆层：SQLite KV 事实总线 + refine 式小步归纳 job（含 LLM 精判 + 证据闸）。

为多 agent 体系解决三件事：

1. 共享事实：各 agent 读写一个带命名空间隔离、CAS 乐观锁、全量审计的 KV 层
2. 归纳不漂移：每日笔记 → 长期记忆，用「watermark 增量 + 按条存储 + 小步 diff + 证据闸」替代整块重写
3. 防幻觉：LLM 归纳产出的每一条断言，都要过证据闸（原文支撑校验，宁拦勿放）

---

架构

┌─ 归纳 job（consolidate_v2.py）── 切片 → notes 源证据 → watermark → 候选匹配
│        → LLM 小步 diff（append/replace/noop）→ 5 道闸 → CAS 写回 durable/
├─ 共享层服务（shared_memory.py）── HTTP KV + 命名空间写隔离 + 审计 + 工单状态机
└─ 数据迁移（v4_migrate.py）── 一次性 DDL（新列 + 新表 + content_hash 回填）

快速开始

1. 启动共享记忆层

# 依赖：Python 3.8+，零第三方库（纯标准库）
export SHARED_MEMORY_DB=./memory.db          # 数据库路径
export SHARED_MEMORY_TOKENS=./tokens.json    # agent token（sha256 存储）
python3 shared_memory.py                       # 监听 0.0.0.0:9813

tokens.json 格式（每个 agent 一个 token，值存 sha256 哈希）：

{"openclaw": "<sha256(token)>", "dsh": "<sha256(token)>"}

2. 迁移（可选，v4 新列/新表）

cd v4
python3 v4_migrate.py --db ./memory.db --dry-run   # 看计划
python3 v4_migrate.py --db ./memory.db --apply      # 真正迁移（自动备份）

3. 归纳 job（refine 式小步更新）

cd v4
# 规则模式（确定性，零 LLM 依赖）
python3 consolidate_v2.py --memory-dir ./memory --dry-run

# LLM 精判模式（分类干货 vs 流水 + 证据闸防幻觉）
export LLM_ENDPOINT=https://your-endpoint/v1   # 任何 OpenAI 兼容端点
export LLM_API_KEY=your-key
export LLM_MODEL=your-model
python3 consolidate_v2.py --memory-dir ./memory --dry-run --llm

每日笔记格式（./memory/YYYY-MM-DD.md）：

## 决策
- 决定本周内升级书房 mesh 节点固件。

## 流水
- 今天天气不错，下午喝了两杯咖啡。

归纳 job 会把「决策」写入 durable，把「流水」判 noop 丢弃。

核心设计

refine 式小步更新（不是整块重写）

• watermark 增量：只处理上次之后的笔记，幂等
• 按条存储：durable/<topic>/<slug>，每条独立，改动影响面 = 单条
• 小步 diff：append（新干货）/ replace（同主题更新）/ noop（流水丢弃）/ delete（推翻旧结论）
• CAS 乐观锁：写前读 version，写回带 expected_version，冲突 409 放弃不盲写

5 道闸（写回前校验）

1. schema：op/target/text 合法
2. 证据真实性：evidence_item_ids 必须指向本批 notes（防伪造）
3. read_only / pinned：豁免条目不覆盖
4. 体积：≤80 字 + ≤max_bytes 字节
5. LLM 证据闸（LLM 模式）：断言能否被证据原文支撑，拦幻觉

命名空间写隔离

每个 agent 只能写自己的 namespace，越权 403。secret 级内容仅用户可写。

目录结构

.
├── shared_memory.py          # 共享层 HTTP 服务（纯标准库）
├── shared-memory-README.md   # 服务接口文档
└── v4/
    ├── v4_migrate.py         # 一次性 DDL 迁移
    ├── consolidate_v2.py     # 归纳 job（规则 + LLM 双模式）
    ├── llm_golden_impl.py    # LLM 精判 + 证据闸实现
    └── test_v4.py            # 自检（50 项）

测试

cd v4
python3 test_v4.py            # 50 项自检（迁移/切片/去重/闸门/CAS/幂等）

License

MIT

设计背景

这套归纳机制来自一个真实的多 agent 运维/业务协作体系（6 个 agent 共享记忆）。原 v1 每天把近 7 天事件整块重写进一个 blob，导致旧结论被冲掉、重复归纳、LLM 幻觉无闸门。v2 用 refine 式小步更新重构，核心不是「换更强的模型」，而是「换更新纪律」——小步、稳定、可回滚。

相关设计文档：v4/ 内的注释与 test_v4.py 的用例即规格说明。