跨Agent记忆共享
> [状态] Hermes 使用内置 MemoryProvider（config.yaml: memory.provider=''），未配置 cross-agent-memory MCP server。本技能为可选高级功能，适用于需要跨 Agent 共享记忆的场景。Hermes 默认记忆系统已满足日常需求。
核心事实（保留这些，其余可精简）
1. 存储方案优先级（强制顺序）
| 优先级 | 方案 | 说明 | 适用场景 |
|---|---|---|---|
| 1 (默认) | JSONL 文件存储 | 纯 Python 实现，零数据库依赖，5 分钟完成 | 单机轻量场景，跨设备同步 |
| 2 (备选) | MySQL 8.0 | Windows 原生，需自行安装配置 | 大数据量/高频写入/多 Agent 并发 |
规范：默认 JSONL，备选 MySQL。MySQL 不可用时自动降级到 JSONL。数据量 >10,000 条或搜索性能下降时，用户自行安装 MySQL 并执行迁移（migrate_to_mysql.py）。
2. 先读后动（Read Before Write）
| 操作 | 先读（必须） | 后动（条件） |
|---|---|---|
| 写入记忆 | 先读现有记忆查重 | 无重复才写入，有重复则合并 |
| 更新记忆 | 先读当前内容 | 仅改变化的字段，保留其他 |
| 删除记忆 | 先确认存在 | 删除前创建备份（trash/，可恢复），统一锁内执行 |
| 迁移数据 | 先扫描源数据 | 确认目标表结构后再迁移 |
> 删除保护（v6.22 强化）：memory_delete 永不裸删——删除前把命中记录复制到 trash/<时间戳>/ 备份目录，找不到 fact_id 时返回 found=False 且不做任何删除，整个过程在统一写入锁内完成。误删可从 trash/ 对应时间戳目录恢复。
3. 最小依赖
# JSONL / CLI 模式（默认，零数据库，最小依赖）
pip install "fastmcp==1.0.0" "mcp==1.0.0" filelock
# MCP server 模式追加（fastmcp 以 uvicorn 拉起服务，仅 MCP 模式需要）
pip install "uvicorn>=0.30,<1.0"
# MySQL 模式追加（可选，仅 MySQL 后端需要）
pip install "pymysql>=1.1,<2"
# LLM 提炼（可选）
pip install openai anthropic
注意：mcp 与 OpenTelemetry 库冲突，必须锁定 mcp==1.0.0；依赖版本以本节清单为准（本清单即权威声明）。
> 依赖优雅降级（v6.24 起）：filelock 缺失时不会崩溃——自动降级为 HAS_FILE_LOCK=False，仅打印警告并照常读写（CLI / JSONL 存储模式完全可用）。代价：此时并发写入无文件锁保护，单 Agent 串行或低频写入不受影响，但多 Agent 高频同写同一文件存在覆盖竞态——高并发场景请安装 filelock。fastmcp / uvicorn 缺失时，MCP server 模式启动会先输出友好报错与 pip install 指引再退出，CLI 与 JSONL 存储模式不受影响。
4. 数据库与端口
- 库名：
cross_agent_memory - 端口：
3306 - 主表：
memories（fact_id, fact, agent_id, level, confidence, tags...） - 关联表：
memory_agents（支持多 Agent 共享同一记忆）
5. MCP 工具（mcp_server.py，共 8 个工具：7 个功能工具 + 1 个验证工具 memory_verify）
| 工具名 | 参数 | 说明 |
|---|---|---|
memory_write |
agent_id, fact, skip_refine | 写入共享记忆，支持去重 |
memory_search |
query, agent_id?, days? | 搜索记忆 |
memory_read_all |
agent_id?, days? | 全量读取近 N 天共享记忆 |
memory_boot_context |
agent_id, max_items? | 获取启动上下文（自动注入关键记忆） |
memory_stats |
days? | 统计信息 |
memory_delete |
fact_id, agent_id?, scope? | 删除指定事实记录（先备份到 trash/，可恢复） |
memory_verify |
agent_id? | 验证系统完整性 |
memory_refine_batch |
agent_id?, days? | 批量提炼原始记忆 |
6. agent_id 隔离（跨系统共享示例）
| 系统 | agent_id 示例 |
|---|---|
| Hermes | hermes_main, hermes_pm, hermes_dev |
| WorkBuddy | workbuddy_main, workbuddy_pm |
每个 Agent 系统必须使用唯一的 agent_id 前缀，避免冲突。
> 严格隔离（v6.22）：memory_search / memory_read_all / memory_boot_context 新增 scope 参数——
> - scope="mine"：仅返回 agents 列表包含本 agent_id 的记录，落实数据隔离，调用方须传入真实 agent_id（未知身份返回空，绝不泄漏）。
> - scope="all"（默认）：返回跨 Agent 共享的全部记忆，保持向后兼容。
> 写入时每条记录都会打上 agent_id 标签；memory_delete 同样支持 scope="mine" 仅删本 Agent 的数据。
>
> 设计边界声明（v6.22.3，第四轮审计 P1-2）：scope="all" 是跨 Agent 共享读设计，不是隔离边界——
> 本技能定位为同一 tenant 内多 Agent 的共享记忆层，任何能连上 MCP server 的调用方本就可读全量
> （MCP 协议无身份验证层）。因此未知身份（unknown/mcp_server/mcp_scheduler）在 scope="all"
> 下返回全量属预期行为，此时响应带 warning 字段显式提示；真正的隔离边界只有 scope="mine"。
> 若部署场景要求"未识别身份不得读全量"，应在 MCP 网关层做准入控制，而非依赖本技能的 scope。
7. 记忆分级（v3.0）
core— 核心记忆（启动时优先注入）important— 重要记忆normal— 普通记忆temp— 临时记忆
启动时通过 memory_boot_context 自动获取关键记忆（解决"失忆"问题）。
8. 配置优先级（环境变量 > 配置文件 > 默认值）
| 优先级 | 配置源 | 说明 |
|---|---|---|
| 1 (最高) | 环境变量 CROSS_AGENT_MEMORY_DB_* |
启动时设置，覆盖配置文件 |
| 2 | memory_data/db_config.json |
各系统独立配置文件 |
| 3 (最低) | 默认值 | localhost:3306, root, 空密码 |
环境变量：CROSS_AGENT_MEMORY_DB_HOST/PORT/USER/PASSWORD/NAME（连接参数）、CROSS_AGENT_MEMORY_AGENT_ID（Agent 身份）、CROSS_AGENT_MEMORY_BASE（存储根目录覆盖；智能默认：沿用 ~/.hermes/memory_data，否则中性 ~/.cross-agent-memory/memory_data）。
9. 跨系统共享关键步骤（Hermes + WorkBuddy，至少三点）
- 共享 db_config.json：两个系统的
db_config.json包含相同的数据库连接参数（host/port/user/password/database/charset），指向同一个cross_agent_memory库。 - 各自唯一 agent_id：Hermes 用
hermes_*，WorkBuddy 用workbuddy_*前缀，写入时带各自 agent_id。 - 指向同一 MySQL：创建共享库
CREATE DATABASE cross_agent_memory CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;，所有系统配置指向它。 - （可选）通过
CROSS_AGENT_MEMORY_AGENT_ID环境变量为每个 Agent 指定唯一 ID。
10. 首次加载强制初始化 JSONL
首次加载 skills 后必须自动执行探测脚本：
# 探测；若 JSONL 未初始化则自动初始化（默认执行）
python scripts/detect_storage.py
# 仅检查存储状态，不初始化（CI / 状态巡检，v6.22 补齐）
python scripts/detect_storage.py --check-only
流程：加载 skill → 自动调用探测脚本 → 探测 MySQL（备选）→ 若 MySQL 不可用则初始化 JSONL（daily/ shared/ refined/ audit/ 目录 + index.jsonl + config.json，与 shared_memory.ensure_dirs 一致）→ 记录状态 → 存储就绪。探测顺序：CROSS_AGENT_MEMORY_DB_* 环境变量 > memory_data/db_config.json > 内置默认值（127.0.0.1:3306/root）；连不上即静默落 JSONL——零配置机器的体验就是纯 JSONL，无任何手工步骤。
> 真实存储结构（v6.22 修正）：记忆落盘为 shared/<日期>.jsonl（每条带 fact_id/agents/fact/date 等字段）+ 全局 index.jsonl。旧文档提到的 memory.json/skills.json/sessions.json 已废弃，不再创建。
输出格式说明：
- stdout = 纯 JSON（供程序解析，json.loads() 可直接解析）
- stderr = 人类可读摘要（供人类阅读）
- 示例 JSON 字段：timestamp, agent_id, memory_base, storage_type（值 mysql/jsonl）, mysql{available,database_exists,tables}, jsonl{available,records}
程序解析：python scripts/detect_storage.py | python -m json.tool
人类阅读：python scripts/detect_storage.py
11. 存储位置
- Obsidian Vault 共享记忆库：
06-共享记忆库/（01_Memory/、02_Skills/） - 本地：
~/.hermes/memory_data/（daily / shared / refined 子目录）；全新环境无此目录时自动落到中性位置~/.cross-agent-memory/memory_data/（无需手工建目录） - 配置：
~/.hermes/memory_data/db_config.json - 已废弃：
~/.hermes/workspace/obsidian-shared-library（不再使用）
定期维护（v6.22 新增）
为保证长期可靠运行（TRACE·E 内容完整度），建议按以下节奏维护：
- 日常巡检：
python scripts/verify.py health（综合）/python scripts/verify.py memory（记忆完整性）/python scripts/detect_storage.py --check-only（存储层状态）。 - 删除恢复：误删记录可在
trash/<时间戳>/找到备份，把对应.bak中 JSONL 重新追加回shared/<日期>.jsonl即可恢复。 - 迁移/批量操作前先备份：
python scripts/verify.py backup生成状态快照；升级 MySQL 前先python scripts/migrate_to_mysql.py --dry-run预览。 - 清理 trash/ 与过期审计：
trash/与audit/会随时间增长，可定期归档或删除旧文件（删除前先确认无待恢复项）。 - 多副本同步（作者机维护用，SkillHub 用户可忽略本条）：作者机有多个物理副本（WorkBuddy 编辑源 / Hermes / QClaw / Obsidian 等），任何一处修改后必须运行
python scripts/sync_copies.py（先--dry-run预览）同步到其余副本；规范源与副本清单见scripts/sync_copies.py顶部注释（含--source/--purge/--quarantine用法）。同步后重启相关会话生效。
场景 → 工具速配
| 你要做的事 | 用什么 |
|---|---|
| 记住一条事实 | memory_write（MCP）/ shared_memory.py write（CLI） |
| 找相关记忆 | memory_search / shared_memory.py read --query |
| 启动时注入上下文 | memory_boot_context |
| 看总量与分布 | memory_stats / shared_memory.py stats |
| 删除（可恢复） | memory_delete（自动备份到 trash/） |
| 体检 / 排错 | scripts/verify.py health + scripts/detect_storage.py --check-only |
| 升级 MySQL | references/mysql-integration-guide.md + scripts/migrate_to_mysql.py --dry-run |
常见任务与作答要点
- "存储方案优先级"类问题：答案为两行——
JSONL 文件存储（默认）、MySQL（备选）。 - "跨系统共享配置步骤"类问题：聚焦三点（共享 db_config.json / 唯一 agent_id / 指向同一库 cross_agent_memory:3306），可补环境变量覆盖与建库语句。
- "首次加载探测脚本"类问题：命令为
python scripts/detect_storage.py；stdout 为纯 JSON，stderr 为摘要；列出关键字段。
失败模式速查
| 场景 | 一线修复 | 兜底 |
|---|---|---|
| fact_id 冲突 | 用内容 hash 重算 | 人工确认合并 |
| agent_id 重复 | 检查 agents 列表 | 跳过并记录日志 |
| 写入超时/失败 | 返回结构化错误（error/message/hint）；MySQL 模式自动降级 JSONL | 按 hint 排查后重试 |
> 详细排错命令与恢复步骤见 EXAMPLES.md「四、故障排除」；运行级健康巡检见上文「定期维护」。
设计初衷一句话
为所有 AI Agent 提供统一记忆共享能力：同一 tenant 共享，agent_id 隔离，LLM 提炼去重，自动注入，自托管 MySQL（降级 JSONL），完全本地数据主权。
验证
- 历史审计：v6.21 前三副本 57/57 通过（fastmcp 依赖、密码走 env、无 TiDB 残留、无硬编码路径、无裸 except 等）；
- 审计轨迹为本地 JSONL 文件（
AUDIT_DIR/<日期>.jsonl），可通过scripts/verify.py health或stats命令查看运行状态； - v6.21.1：按 TRACE 测评报告完成文档纠偏——工具清单修正为 8 个（补
memory_read_all）、移除不存在的audit_logs表描述、README/EXAMPLES 与实际代码对齐、清理 6 篇过期流程文档。 - v6.22.0：按 TRACE 测评深挖可靠性/有效性短板——修复
detect_storage存储模型错配并补齐--check-only；memory_delete删除保护（先备份 trash/、先确认存在、加锁）；统一memory.lock并发锁覆盖写/删/提炼；scope参数落实 agent_id 严格隔离；统一错误结构避免泄漏 traceback。
质量门禁（v6.21 新增）
本版本由「穷人版 RSI」流水线自动进化并通过双门禁回归验证：
- 能力门禁（22 道冻结任务，覆盖事实提取与操作产出）：22/22 通过；
- 一致性门禁（LLM 裁判审查内部自洽）：3/3 通过，修复了 v6.20 的 MCP 工具数（5/6/7）自相矛盾等问题；
- 相对 v6.20（736 行）篇幅压缩约 78%，能力零损失。详细文档见 references/。
