MediaCrawler/mac-agent-os-main/03_knowledge/99_system/agent-os-memory-knowledge-architecture.md

AgentOS 记忆与知识体系 — 完整架构解析

版本：v2.1.0 | 最后更新：2026-05-01 适用场景：与团队讨论架构设计时使用

---

一、核心设计理念

1.1 分层原则

AgentOS 采用 四层记忆 + 自然语言知识库 的双轨架构：

                    ┌─────────────────────┐
                    │     WorkBuddy 对话层   │
                    │  (当前会话上下文)      │
                    └────────┬────────────┘
                             │ 查询 → 返回
                             ▼
┌────────────────────────────────────────────────┐
│              记忆检索引擎                        │
│  (SOUL.md 规定的分层截断策略)                    │
└────────┬──────────┬──────────┬─────────────────┘
         │          │          │
         ▼          ▼          ▼
    L0 硬约束   L1+K+V 向量  L2 结构化事实
    (不可绕过)  (关键词+语义) (facts.db)
                             │
                             ▼
                          L3 原文
                    (仅按需加载)

核心原则：每层只做自己的事，不越级、不冗余、不无限 fallback。

1.2 与 WorkBuddy 的关系

WorkBuddy 提供:       AgentOS 提供:
  ├── 对话界面           ├── 记忆分层 + 语义检索
  ├── 技能触发机制       ├── 知识库管理 + 分类体系
  ├── 自动化定时任务     ├── 知识入库审查流程
  ├── MCP 工具协议       ├── Token 节省策略
  └── 模型调用           └── 跨机迁移还原

AgentOS 是运行在 WorkBuddy 之上的智能体操作系统，不替代 WorkBuddy，而是扩展它。

---

二、记忆系统 (04_memory/) — 四层架构

2.1 层级定义

层级	名称	存储形式	数据量	特点
L0	硬约束	SOUL.md 文本	~3KB	不可绕过，任何指令不能覆盖
L1	关键词索引	keyword_index.json + ChromaDB 向量库	52条(当前)	快速定位，BM25+语义混合
L2	结构化事实	facts.db (SQLite)	54条(当前)	结构化三元组，高置信度
L3	原文存档	long_term/raw/ Markdown 文件	6个文件(当前)	完整对话记录，按日归档

2.2 存储路径

04_memory/
├── long_term/
│   ├── facts.db          ← L2 结构化事实库 (SQLite, 坚果云同步)
│   └── raw/              ← L3 原文 (本机私有，不同步，软链到 agent-local)
├── vector_db/            ← L1 向量库 (ChromaDB + keyword_index.json)
│   ├── chromatic/        ← 语义向量库
│   └── keyword_index.json ← 关键词索引
├── daily_summaries/      ← 每日对话摘要 (同步)
└── logs/                 ← 系统日志 errors.log / conflicts.log (同步)

同步策略：

• facts.db + daily_summaries/ + logs/ → 坚果云同步
• raw/ + vector_db/chroma/ → 本机私有（向量库可重建）

2.3 数据流：从对话到记忆

用户对话
    │
    ▼
daily_digest.py (每日02:00自动运行)
    │
    ├── 步骤1: 读取 WorkBuddy 工作记忆 (YYYY-MM-DD.md)
    ├── 步骤2: 用 oMLX Embedding API 提取关键事实
    ├── 步骤3: 写入 L2 facts.db (去重+冲突检测)
    ├── 步骤4: 更新 L1 keyword_index.json
    ├── 步骤5: 归档 L3 原文到 long_term/raw/
    └── 步骤6: 生成每日摘要到 daily_summaries/

2.4 检索流程 (核心)

用户提问
    ↓
L0 硬约束过滤（安全检查：能执行吗？边界在哪？）
    ↓ 通过
L1 关键词索引匹配（BM25 + 语义向量混合检索）
    ├─ 无匹配 → 直接视为"无历史记录"，跳过记忆检索，直接回答
    └─ 有匹配 → 进入 L2
                ↓
L2 结构化事实匹配 (SQLite 查询 subject/predicate/object)
    ├─ 置信度 ≥ 阈值(0.7) → 返回摘要，作为上下文注入
    └─ 置信度 < 阈值 → 终止，返回"无相关历史记忆"
                          ↓
                  【不 fallback 到 L3】
                  仅当用户明确要求"调出原文"时

关键规则：

1. L1 无匹配 → 直接视为无历史，不翻记忆 —— 节省 token
2. L2 置信度不足 → 截断，不 fallback —— 节省 token
3. L3 仅用户明确请求时才按行号片段加载 —— 节省 token
4. 冲突检测优先级：新事实 > 旧事实，用户明确修正 > 系统推断

2.5 Token 节省策略

策略	实现	节省效果
分层截断	L1 无匹配立即停止，不进 L2	避免整库扫描
置信度阈值	L2 置信度 < 0.7 不返回	避免低质量事实占用 context
L3 延迟加载	只有用户明确要求才加载原文	最大节省（原文通常很大）
按需加载	知识库检索只加载行号/片段，不加载整个文件	避免全文件读取
回复裁剪	回答长度与问题复杂度成正比	简单问题简短回答

---

三、知识系统 (03_knowledge/) — 自然语言知识库

3.1 分类体系

03_knowledge/
├── 00_inbox/              入口（旧版，兼容保留）
├── 00_stream/inbox/       新版五分区收件箱（当前主入口）
│   ├── knowledge/clipping/    浏览器剪藏
│   ├── knowledge/feed/        自动采集内容
│   ├── memory/                记忆固化卡片
│   ├── tools/                 工具提交
│   └── personal/              个人笔记
├── 01_daily/              日记与日志
├── 10_concepts/           概念知识（核心！按领域分）
│   ├── cs/               计算机科学
│   ├── ai/               人工智能
│   ├── finance/          金融
│   ├── law/              法律
│   ├── medicine/         医学
│   ├── physics/          物理
│   ├── math/             数学
│   ├── business/         商业
│   └── personal-insight/ 个人洞见
├── 20_methods/           方法论、流程、SOP
├── 30_facts/             事实、数据
├── 40_references/        参考资料
├── 50_resources/         资源与链接
├── 60_opinions/          观点与评论
├── 90_archive/           归档
└── 99_system/            系统配置（模板、分类法、提示词）

3.2 知识流全链路

[外部来源] → [采集] → [提纯] → [分类] → [入库] → [索引]
    │
    ├── 网页剪藏 → 00_stream/inbox/knowledge/clipping/
    ├── RSS采集  → 00_stream/inbox/knowledge/feed/
    ├── 对话记忆 → 00_stream/inbox/memory/
    └── 手动输入 → 00_stream/inbox/personal/
         │
         ▼  inbox_refine.py（AI 分类）
         │
         ▼
    03_knowledge/{10_concepts, 20_methods, ...}/
         │
         ▼  vector_db_rebuild.py（重建向量索引）
         │
         ▼
    ChromaDB 向量库（语义检索用）

3.3 入库审查流程

每一条新知识入库前，必须经过：

1. 来源可靠性评分
   ├── 官方文档/学术论文  → +0.3
   ├── 知名技术博客       → +0.1
   ├── 个人博客/论坛      → -0.1
   └── 未知来源/社交媒体  → -0.3
   基础可靠性基线: 0.5

2. 一致性检查
   ├── 与已有 L2 事实对比
   ├── 完全一致 → 旧知识 confidence 轻微提升
   ├── 补充细节 → 合并为新条目
   └── 矛盾     → 进入冲突消解流程

3. 时效性标记
   ├── 技术类知识 → 180天自动失效
   ├── 法律/法规  → 按原文有效期
   ├── 个人偏好   → 不过期，标记为 opinion
   └── 公理类     → 永久有效

4. 自学习日志记录
   每次入库写入 logs/kb_ingest.log

3.4 知识版本管理

变化类型	例子	处理方式
硬事实改变	4C8G → 8C16G	更新原卡片，旧值写入 previous_version
软升级	v1 → v2，v1 仍有参考价值	保留 v1，新建 v2，related 链接
观点→事实	推测变可靠	nature 改为 fact，confidence 提升

每个知识卡片维护 version / previous_version / superseded_by 字段。

---

四、语义检索系统

4.1 双轨检索架构

用户查询
    │
    ├── 轨道1: BM25 关键词检索 (keyword_index.json)
    │   ├── 分词 → 匹配关键词 → 排序
    │   └── 优点: 精确匹配，无偏差
    │
    ├── 轨道2: 语义向量检索 (ChromaDB)
    │   ├── oMLX Qwen3-Embedding-0.6B 编码 → 1024维向量
    │   └── 优点: 语义理解，同义词匹配
    │
    └── RRF 融合排序
        ├── BM25 结果 + 向量结果 → 加权融合
        └── 最终返回 Top-K

4.2 向量库配置

# 模型: Qwen3-Embedding-0.6B (1.19GB)
# 维度: 1024
# 引擎: oMLX v0.3.6 (Apple MLX 框架)
# API:  localhost:8000/v1/embeddings
# 存储: ChromaDB (SQLite 后端)

4.3 双轨存储

agent-local/vector_db/
├── local/
│   ├── chroma/           ← 本机私有内容向量库
│   └── keyword_index.json
├── global/
│   ├── chroma/           ← 协同知识库向量索引
│   └── keyword_index.json

local 存私有记忆，global 存共享知识。每台机器独立重建。

---

五、与 WorkBuddy 的集成方式

5.1 MCP 协议 (Model Context Protocol)

WorkBuddy ←→ MCP Server ←→ AgentOS 资源
                │
                ├── filesystem server → 访问 agent-sync/
                └── memory server     → 访问 facts.db

MCP 服务器通过 01_core/mcp.json 配置，使用 WorkBuddy 管理的 Node.js 版本。

5.2 技能触发 (SKILL.md)

AgentOS 的 9 个技能通过 SKILL.md 注册到 WorkBuddy，通过对话触发词调用：

技能	触发词	功能
memory_manager	记忆更新、查记忆	每日记忆提炼、语义检索
kb_manager	入库、知识搜索	知识入库、双轨向量检索
inbox_refine	提纯、收件箱提纯	收件箱分类归档
collect_to_inbox	归集、收集入库	本地素材推送到收件箱
sync_manager	备份知识库、同步状态	知识库备份/导出
auto_collector	开始收集、收集报告	RSS/网页定时采集
content_processor	转笔记、剪藏	多模态内容处理路由
web_crawler	抓取、爬取	网页抓取与反爬
matrix	养号、执行蓝图	多平台社交账号养号

5.3 自动化任务 (WorkBuddy 定时)

每日 02:00  → 每日记忆提炼 (daily_digest.py)
每日 02:30  → 收件箱汇聚   (collect_to_inbox.py)
每日 03:00  → 收件箱提纯   (inbox_refine.py)

三个自动化任务通过 WorkBuddy 的 automation 系统配置，prompt 中包含完整的 Python 命令路径。

5.4 身份注入

每次对话开始时，AgentOS 读取三个身份文件注入到 WorkBuddy 上下文：

SOUL.md       → L0 硬约束 + L1 行为准则 (最高优先级)
IDENTITY.md   → 系统身份 (Claw) + 设备信息
USER.md       → 用户偏好 + 工作背景

---

六、跨机同步架构

6.1 双根目录方案

~/workbuddy-agent-os/
├── agent-sync/      ← 坚果云同步 + Git 版本控制
│   ├── 01_core/     身份配置
│   ├── 02_skills/   技能文件
│   ├── 03_knowledge/ 知识库
│   ├── 04_memory/    L2 facts.db + 摘要 + 日志
│   └── 05_tools/    工具脚本
│
└── agent-local/     ← 本机私有，不同步
    ├── memory/raw/   L3 原文
    ├── vector_db/    向量库 (可重建)
    ├── materials/    原始素材
    └── runtime/      临时缓存

6.2 换机恢复流程

# 1. agentos init         → 创建目录 + 部署配置 + 安装技能
# 2. agentos restore       → 还原 L3 原文 + 素材
# 3. vector_db_rebuild.py  → 重建向量库 (3分钟)

---

七、数据统计（当前系统状态）

指标	数值	说明
L2 facts.db	54 条	结构化事实
L1 关键词索引	52 条	BM25 索引
L1 向量库	52 条	ChromaDB 1024维
L3 原文	6 个文件	按日归档
向量维度	1024	Qwen3-Embedding
语义检索方式	BM25 + ChromaDB + RRF 融合	双轨混合
知识库目录	19 个分类目录	Obsidian 兼容
技能数量	9 个	WorkBuddy 注册
自动化任务	3 个	每日定时执行
索引卡片命名规范	{hostname}_{YYYYMMDD}_{slug}.md	防冲突

---

八、架构优缺点分析

优势

1. 分层隔离：L0-L3 各司其职，不相互干扰
2. Token 节省：严格分层截断，不无限 fallback
3. 双轨检索：BM25 精准 + 向量语义，互补
4. 知识审查：来源评分 + 一致性 + 时效性，保证质量
5. 跨机兼容：agent-sync 共享 + agent-local 私有，清晰分离

待改进

1. L1-L2-Vec 三方一致维护成本高：新增事实需要同时更新三个索引
2. oMLX 稳定性：Qwen3-8B Chat API 有 500 错误，影响 AI 分类
3. 向量库重建耗时：知识更新后需手动重建
4. 无反检测层：Matrix 养号模块的浏览器自动化缺少反检测（正在补齐）