🧠 unified-agent-memory

Unified Fleet-Wide Agent Memory System for DeepSeek Harness & Multi-Agent Runtimes

跨 Agent 统一持久化记忆系统 — 基于 Obsidian Vault 存储规范与 SQLite FTS5 本地索引的知识生命周期管理基座

产品定位与问题定义 • 核心技术优势 • Obsidian 存储规范 • Agent 全流程自动部署 • 生命周期控制流 • 安全隔离与防护机制

---

📌 产品定位与问题定义

传统 Agent 记忆插件多数绑定于特定的 Agent 运行时（Single-Agent Scope），其存储空间与会话相互隔离，缺乏统一的状态持久化与跨代理知识共享能力。

unified-agent-memory 架构旨在为多 Agent 舰队提供统一的知识管理基座：它允许 dsh、Codex、Claude Code 与 Hermes 等多个独立代理共享基于 Markdown 规范的 Obsidian Vault 知识仓库，配合纯 Python 标准库核心与 SQLite FTS5 本地索引，构建涵盖知识摄取 (Ingestion)、知识晋升 (Promotion)、冲突裁决 (Adjudication) 与衰减遗忘 (Decay/Retention) 的全闭环生命周期管理系统。

---

🚀 核心技术优势

• 统一单一真理来源 (Shared Source of Truth)
  全 Fleet 代理共享一致的 Markdown 知识库规范。开发者与用户可直接借助 Obsidian 等编辑器可视化审计、人工校验或修改代理积累的知识节点。
• 纯 Python 标准库核心 (Zero-Dependency Engine)
  core/ 模块完全基于 Python 标准库（sqlite3, json, hashlib, argparse, os）实现，无外部依赖开销，具备毫秒级冷启动性能。
• SQLite FTS5 本地全文索引 (Local-First High-Performance Search)
  检索索引持久化存储于本地 ~/.unified-memory/index-<vault-hash>.db，按 Vault 隔离；基于 SQLite FTS5 引擎实现毫秒级全文匹配与相关度计算，数据隐私完全归属于本地宿主机。
• 提示词隔离防护与凭据脱敏 (Prompt Injection Defense & Redaction)
  检索输出强制采用 <memory-data> 安全隔离标记包装，明确提示 LLM 区分数据上下文与系统指令；知识摄取前自动对敏感凭据（API Keys/Tokens）执行掩码清洗。
• 完整知识生命周期控制 (Full Lifecycle Pipeline)
  内置完整的状态流转机制：包含写收件箱暂存、Promoter 知识审核归纳、Adjudicator 冲突事实裁决、Atomic Lock 并发文件锁与 Forgetter 定期记忆衰减归档。

---

⚖️ 系统特性对比 (Feature Matrix)

特性维度	🧠 unified-agent-memory	❌ 单 Agent 存储插件 (dsh-mnemon 等)	❌ 外部向量桥接器 (sgme 等)
跨 Agent 共享粒度	全 Fleet 共享 (dsh/Codex/Claude/Hermes)	强绑定单一 Harness 运行时	依赖集中式向量数据库中转
核心组件依赖	纯 Python 标准库，无第三方依赖	依赖 Host 宿主插件环境	需要部署额外的数据库中间件
生命周期控制能力	包含 摄取/晋升/裁决/遗忘 全链路	通常仅具备 存储+召回 基础功能	仅实现向量空间映射
知识可视化与可介入性	Obsidian 原生 Markdown，人类直接可读	数据库黑盒 / 私有 JSON 格式	向量数据结构不可直观校验
安全审计与防护机制	标签隔离包装 + 凭据正则自动脱敏	依赖上层应用手工干预	易在向量库中泄露明文凭据

---

📂 Obsidian Vault 存储结构规范

系统自动在指定目录生成标准化 Obsidian Vault 存储层层级：

~/Documents/AgentMemory/
├── 00_Inbox/         # 代理提交的待审核临时知识节点 (Draft Notes)
├── 10_Canonical/     # 经 Promoter 归纳晋升的标准化主知识库 (Canonical Notes)
├── 20_Conflicts/     # 多代理矛盾事实等待裁决的队列 (Conflict Queue)
├── 99_Forget/        # 已衰减或废弃的历史知识归档区 (Archived Memories)
└── .vault_config.json # Vault 属性与索引配置文件

---

🏗️ 知识生命周期控制流

flowchart TD
    A[Agent 提交接口: memory_submit] --> B{凭据自动脱敏引擎}
    B -- 匹配 API Key / Token 模式 --> C[应用掩码清洗 REDACTED]
    B -- 校验通过 --> D[写入 00_Inbox/ 暂存区]
    
    D --> E[更新 SQLite FTS5 本地索引]
    D --> F[触发 Promoter 审核 Pipeline]
    
    F -- 事实无冲突 --> G[晋升至 10_Canonical/ 主知识库]
    F -- 存在矛盾记录 --> H[拦截入 20_Conflicts/ 待裁决队列]
    
    H --> I[Adjudicator 裁决机制]
    I --> G
    
    G --> J[Forgetter 记忆衰减 Cron]
    J -- 触发长期衰减条件 --> K[归档至 99_Forget/ 归档区]

---

🤖 Agent 全流程自动部署流程 (Agent-Driven Automated Deployment)

将多 Agent 接入统一记忆系统涉及跨代理配置文件（AGENTS.md / CLAUDE.md 等）的规则注入与校验。根据项目原生架构设计，部署工作完全由 AI Agent (DSH) 主导并自动执行，无需手动修改环境规则文件。

flowchart LR
    A[挂载 dsh 记忆插件] --> B[DSH 识别首次安装通知]
    B --> C[读取任务书 docs/AGENT-DEPLOY.md]
    C --> D[环境检测、安装 Core 与 Vault 模版初始化]
    D --> E[自主装配各 Agent 指令文件 AGENTS.md / CLAUDE.md]
    E --> F[执行 selfcheck 并汇报部署决策]

1. DSH 自主部署流程 (官方推荐机制)

…