# Agent 记忆系统选型与集成策略 (2026-02-25 · v5.0 OpenRouter + pgvector 本地库架构)

> **修订说明 (v5.0)**：将 A 层从 `ChromaDB + Ollama` 切换为 `OpenRouter Embedding API + 本地 PostgreSQL/pgvector`。目标是不运行本地 embedding 模型，同时保留本地向量存储与 Git 增量同步能力。

本方案面向基于 **PARA 架构** 的 Obsidian Vault，提供一套纯 Agent 驱动的记忆系统。系统不依赖 Obsidian 插件，通过 CLI 与大模型协作，解决 Agent "跨 Session 上下文连续性"和"复杂笔记语义召回"问题。

---

## 0. 设计目标与约束

1. **不使用本地 embedding 模型**：避免本机常驻 Ollama。
2. **本地持久化**：向量与元数据留在本地 PostgreSQL。
3. **增量优先**：基于 Git 变更做文件级 `upsert/delete`。
4. **强一致**：删除、重命名、隔离、降阈值时不允许幽灵向量残留。
5. **安全可控**：敏感内容不入检索库；检索注入具备 Prompt 注入防护。

---

## 1. 核心架构：双层记忆模型

### A 层：文档语义记忆（OpenRouter + pgvector）
- **Embedding 生成**：调用 OpenRouter Embedding API。
- **向量存储与检索**：本地 PostgreSQL + `pgvector`。
- **数据源**：`01_Projects`、`02_Areas`。
- **排除目录**：`00_Inbox`、`04_Archive`、`Infrastructure`、`Home-Automation`。

### B 层：事实与偏好记忆（Claude Memory）
- **来源**：动态读取 Claude Code `MEMORY.md`。
- **用途**：补充用户偏好、约束、近期状态。

---

## 2. 组件职责

| 组件 | 职责 | 解决的问题 |
|------|------|-----------|
| OpenRouter Embedding API | 文本向量化 | 不在本地部署 embedding 模型 |
| PostgreSQL + pgvector | 向量持久化与相似度检索 | 本地可控存储、低运维 |
| Git post-commit Hook | 触发增量索引 | 避免全量重建 |
| 黑名单与敏感扫描 | 安全隔离 | 防止凭据入库与注入 |
| Claude MEMORY.md | 偏好/事实注入 | 保持跨 Session 连续性 |

---

## 3. 验收指标（MVP）

1. **Recall@5 >= 70%**（包含 `source`）。
2. **post-commit 不阻塞**：索引后台异步执行。
3. **单文件增量 P95 < 1s**（不含远端 API 网络抖动）。
4. **端到端冷启动 <= 4.5s**（含 OpenRouter 请求）。
5. **安全红线**：敏感目录与敏感内容不得写入 Primary 检索表。
6. **一致性红线**：`delete/rename/quarantine/prune` 后旧 ID 必须删除。

---

## 4. 安全与一致性策略

1. **路径部位精确匹配**：按 `Path.parts` 做目录排除。
2. **内容单命中隔离**：任一高危特征命中即隔离。
3. **强一致删除**：增量事件中 `D/R` 先删旧 ID，再处理新路径。
4. **单写者锁**：索引写操作串行化。
5. **只读上下文注入**：检索结果包装为引用块，禁止当指令执行。
6. **长度截断**：注入前全局 `max_chars=2500`。

---

## 5. 关键权衡

1. **优点**
- 不跑本地模型，设备压力低。
- 向量在本地 DB，数据控制力强。
- 与现有 Git 工作流兼容。

2. **代价**
- embedding 文本会发送到 OpenRouter（不是纯本地隐私）。
- 受网络与 API 可用性影响。
- 需配置 API key 与请求限流/重试策略。