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 向量库配置

```python
# 模型: 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 换机恢复流程

```bash
# 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 养号模块的浏览器自动化缺少反检测（正在补齐）