Dynamics-memory

状态：现行 · N48–N52 已汇合（真实 CLI 首验、可观测性、L2/L3 抽检工具链与审计修正）；决策登记见 analysis/target-architecture.md §9.3；PENDING-08 待人工验收。本页是行为摘要；机械验证入口在 analysis/acceptance_check.py。

LLM agent 的有界长期记忆层

把连续、嘈杂、前后矛盾的项目交互，蒸馏成一个不会堆成"史山"的记忆库。
新会话里一句"接着搞"，agent 就知道进行到哪、上次卡在哪。

全景 · 架构分层 · 记忆动力学 · 可靠性 · 运行 · 配置

30 秒上手

pip install numpy pytest
cp .env.example .env          # ZAI_API_KEY=...

python -m pytest tests/                          # 本地测试；不是远程验证
python -m hybrid_memory.server --project <dir>   # 或被 opencode 插件自动拉起

接入 opencode（官方 CLI 即可，无需源码）：

npm i -g opencode-ai
cd <本仓库> && opencode        # .opencode/plugin/memory-bridge.ts 自动加载并拉起 sidecar

_{给别的项目用：把 memory-bridge.ts 软链到 <项目>/.opencode/plugin/。插件的
@opencode-ai/plugin 依赖按软链的真实路径解析，所以要先在本仓库里跑一次 opencode
（或 cd .opencode && npm i @opencode-ai/plugin）让依赖装好。}

为什么不用现成的两条路

路线	死因
全量 log 塞 context	每轮付 O(log) 的 prefill+KV 扫描，随项目历史线性变贵
原文入向量库	冗余、过期、互相矛盾的副本堆成史山，旧状态压过新状态

log 不是记忆，log 是证据。 记忆是蒸馏产物，进池要过动力学与置信门控；日志留在 L0 冷层，只在需要时按计量回展——永不整段进 prompt。

全景：一条对话的旅程

从主 agent 的一句"以后统一用 bun"，到它成为一条可检索、可归因、可结算的记忆：

flowchart LR
    U("主 Agent<br/>OpenCode") -->|"① 会话事件"| BR["memory-bridge.ts<br/>插件桥"]
    BR -->|"POST /observe"| SVC["sidecar<br/>:17872"]
    SVC --> L0[("L0 证据库<br/>只增不删 · FTS")]
    SVC -.->|"② 信号入队"| Q[["任务机<br/>SQLite 持久交接"]]
    Q -->|"③ --file 文件通道"| H["Hauler<br/>抽候选"]
    H -->|"④ 候选 + 来源"| S["Selector<br/>五路裁决"]
    U -.->|"表达不满"| REV["Reviewer<br/>诊断 + 版本化规则"]
    REV -.->|"持久规则回喂"| H
    S -->|"CREATE"| ENG["记忆引擎<br/>三池动力学"]
    S -->|"CONFLICT"| HR{"human_reviews<br/>待人工审核"}
    HR -->|"accept_new / keep_old"| ENG
    S -->|"REJECT"| X(("不入库"))
    BR -->|"⑤ GET /recall"| SVC
    SVC -->|"⑥ relevant-memories 注入"| U
    BR -->|"⑦ POST /feedback"| SVC
    SVC -->|"useful-hit → V 值结算"| ENG

    classDef agent fill:#FFF3E0,stroke:#E8963C,color:#7A4A00
    classDef core fill:#E8F4FD,stroke:#2B8CBF,color:#0B4F6C
    classDef store fill:#F5F5F5,stroke:#9E9E9E,color:#424242
    classDef risk fill:#FDECEF,stroke:#D65F7F,color:#8A2444
    class H,S,REV agent
    class ENG,SVC core
    class L0,Q store
    class HR,X risk