Agent Memory

面向多智能体协作的低开销结构化通信、非文本状态传递与共享记忆复用原型。

离线首版能力

Planner、Worker、Summarizer 三个独立业务 Agent 进程和非 Agent Coordinator；
TEXT 自然语言基线、STRUCT Protobuf + SharedMemory、FULL Protobuf + SharedMemory + SQLite；
Protobuf v1 握手、能力发现、typed action/result、状态描述符和释放消息；
512 维 float32 非文本状态跨进程传递、SHA-256 校验和显式清理；
稳定 memory ID、规定元数据、关键词/标签/余弦检索及复用回执；
两组各 5 个冻结任务、确定性 ground truth、JSONL 原始事件和 CSV/Markdown 重建；
Mock LLM、真实 OpenAI-compatible 适配器和本地 BGE provider；
openEuler 环境证据采集、SHA-256 完整性校验、正式 run 绑定和三模式报告一致性检查。

当前开发进度（2026-07-28）

离线首版的五项收尾工作已完成本地离线验收：

FULL 模式由 Summarizer 写入带稳定 ID 的记忆，Planner 和 Summarizer 分别显式返回经过候选集合校验的 reused_memory_ids；事件按实际消费 Agent 记录，可证明跨 Agent 复用。
Coordinator 校验并按依赖顺序执行全部 PlanStep；每步 ToolResult 通过 typed StepToolResult 保留并传给 Summarizer，Planner 和 Summarizer 的 LLM 输入包含完整 typed task、计划、证据正文、工具结果和候选记忆。
Agent 正常退出、超时或强制终止后，Coordinator 都会使用保留的状态描述符执行 SharedMemory 兜底清理，不再只清空内存登记表。
TEXT 与 Protobuf 都覆盖 Protobuf v1 的控制消息和错误回执；TEXT 模板对分隔符、换行和空白做可逆转义，Protobuf 支持 MemoryQuery/MemoryResult 和逐步工具结果。
JSONL 与重建报告覆盖实际 TEXT 字符数、wire bytes、状态创建与传递、LLM 调用、显式记忆复用、质量、任务耗时和 run 耗时；资格测试代码覆盖三种模式各自的完整十轮链路。
环境证据模块可采集 environment.json、pip-freeze.txt、os-release.txt、uname.txt、doctor.json 和校验和；只有显式提供通过检查的 openEuler 证据且使用非 Mock provider 时，run manifest 才能标记为正式。正式报告会拒绝混合本地数据或不可比较的三模式 run。

截至 2026-07-28，Windows/Python 3.12 本地检查通过 Ruff、mypy、compileall、141 个单元测试、3 项规定的轻量 Mock 集成测试、6 项十轮资格测试和 doctor 的 7 项检查。目标 openEuler VM 上的同一源码通过 strict doctor、静态检查、141 个单元测试和 6 项十轮资格测试。

离线 mock 运行使用确定性 512 维测试向量；state 开启的远程运行会切换到本地 BGE，且只有 models.lock 同时记录已验证 revision、文件哈希和许可证状态后才允许启动，禁止静默退回测试向量。

目标 openEuler 24.03-LTS-SP3 x86_64 VM 已从 GitHub 部署 commit dc4541e。真实 BGE 的 14 个文件与不可变 revision 29ee8f619cff1eb2efae93ff802e01a877212d16 完整匹配，MIT 许可及离线 (512,) float32 输出已验证。使用真实 qwen3.6-flash、prompt v4 和同一冻结 taskset 的 TEXT、STRUCT、FULL 各一次十轮正式运行均完成，正式报告可由原始事件重建；Docker 与每模式 3 次的可选稳定性重复仍未执行。

正式环境证据流程

以下命令是目标环境的正式操作入口；已验证结果和 run ID 见 docs/开发进展与验证状态.md：

EVIDENCE_DIR=experiments/runs/environment/oe-$(date -u +%Y%m%dT%H%M%SZ)
python scripts/capture_environment.py --output "$EVIDENCE_DIR" --formal
python scripts/run_experiment.py \
  --config configs/text.yaml \
  --formal-evidence "$EVIDENCE_DIR"

STRUCT 和 FULL 使用同一个证据目录分别执行。环境采集不会调用远程 LLM 或加载 BGE；正式 chain 自身必须使用真实远程 provider，STRUCT/FULL 还会继续执行现有的 verified models.lock 和真实本地 BGE 门禁。Windows、Mock、失败 doctor、脏工作树或被篡改的证据包都不能生成正式标记。

安装与基础检查

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m pip install -e . --no-deps
.\.venv\Scripts\python.exe -m agent_memory doctor
.\.venv\Scripts\python.exe -m ruff format --check .
.\.venv\Scripts\python.exe -m ruff check .
.\.venv\Scripts\python.exe -m mypy src scripts
.\.venv\Scripts\python.exe -m compileall -q src scripts tests
.\.venv\Scripts\python.exe -m pytest tests/unit -q
.\.venv\Scripts\python.exe -m pytest `
  tests/integration/test_runtime.py::test_text_single_task_uses_three_business_agent_processes `
  tests/integration/test_runtime.py::test_struct_task_transfers_and_releases_shared_state `
  tests/integration/test_runtime.py::test_full_a1_to_a2_reuses_traceable_memory -q

完整十轮、远程 API 和 openEuler 测试分别带 qualification、remote_llm、openeuler marker，本次基础检查不执行。

CLI

python -m agent_memory doctor [--strict-openeuler] [--json]
python -m agent_memory run-chain --config configs/full.yaml [--formal-evidence PATH] [--json]
python -m agent_memory report --runs experiments/runs [--json]
python -m agent_memory inspect-memory --db RUN_DB_PATH [--json]

详细架构、协议、测试和最终验收边界见 docs/系统设计与环境部署方案.md，环境步骤见 docs/部署文档.md。