my-vault/06_Metadata/AGENT_MEMORY_IMPLEMENTATION_TASKS_2026-02-25.md

# Agent Memory 实施任务清单（2026-02-25 · 可监控执行版）

## 0. 目标与范围
- 目标：落地 `OpenRouter + 本地 PostgreSQL/pgvector + Git 增量同步 + Claude Memory`。
- 范围：实施 A/B 记忆主链路、安全隔离、强一致同步、可观测与验收。
- 不包含：Mem0、Cognee 关系图扩展。

---

## 1. 执行看板（实时更新）

状态枚举：`TODO` / `DOING` / `DONE` / `BLOCKED`

| 任务ID | 任务 | 状态 | Owner | 开始时间 | 完成时间 | 证据（命令输出/文件） | 备注 |
|---|---|---|---|---|---|---|---|
| T1.1 | 检查 uv | DONE | windy | 2026-02-25 15:53 +0800 | 2026-02-25 15:53 +0800 | `uv --version` -> `uv 0.10.6 (Homebrew 2026-02-24)` | 通过 |
| T1.2 | 检查 Docker/psql | DONE | windy | 2026-02-25 15:53 +0800 | 2026-02-25 15:53 +0800 | `docker --version` -> `29.2.0`; `psql --version` -> `18.2` | 通过 |
| T1.3 | 检查 OpenRouter key | DONE | windy | 2026-02-25 15:53 +0800 | 2026-02-25 16:14 +0800 | embedding probe: `status=200`, `embedding_len=1536` | key+模型可用 |
| T2.1 | `uv sync` 安装依赖 | DONE | windy | 2026-02-25 15:54 +0800 | 2026-02-25 15:54 +0800 | `uv sync --project .scripts/memory` 成功；`uv run --project .scripts/memory python -V` -> `Python 3.12.8` | 首次因沙箱限制失败，提权后通过 |
| T2.2 | 配置 `.env.memory` | DONE | windy | 2026-02-25 15:54 +0800 | 2026-02-25 16:14 +0800 | `.env.memory` 已填充真实 OpenRouter 配置并通过 embedding probe | 通过 |
| T2.3 | 校验 `.gitignore` | DONE | windy | 2026-02-25 15:54 +0800 | 2026-02-25 15:54 +0800 | `rg` 命中 `.env.memory`(90) `.memory-sync.log`(194) `memory_eval/results/`(218) | 通过 |
| T3.1 | 启动 pgvector | DONE | windy | 2026-02-25 16:03 +0800 | 2026-02-25 16:03 +0800 | 用户确认 compose 已启动；后续 `psql` 连通验证通过 | 通过 |
| T3.2 | 初始化 schema | DONE | windy | 2026-02-25 16:03 +0800 | 2026-02-25 16:03 +0800 | `psql ... -f .scripts/memory/schema.sql` 执行成功 | 表/索引已创建 |
| T3.3 | 数据库连通性验证 | DONE | windy | 2026-02-25 16:03 +0800 | 2026-02-25 16:03 +0800 | `SELECT 1` 返回 `1`；`\\dt memory_*` 可见两张表 | 通过 |
| T4.1 | 全量索引 | DONE | windy | 2026-02-25 16:04 +0800 | 2026-02-25 16:17 +0800 | `ingest_vault.py` 完成：`[DONE] ... primary=81 secure=79 failed=2`; SQL: `memory_primary=81` | 已加入单文件 embedding 异常容错 |
| T4.2 | 查询链路验证 | DONE | windy | 2026-02-25 16:04 +0800 | 2026-02-25 16:17 +0800 | `query_pgvector.py \"总结我最近的重点项目\"` 返回 `<retrieved_context source=\"...\">` | 链路通过 |
| T4.3 | 安装 Git Hook | DONE | windy | 2026-02-25 16:03 +0800 | 2026-02-25 16:03 +0800 | `bash .scripts/memory/install-hook.sh` 成功；`.git/hooks/post-commit` 含 `memory async index hook` | 通过 |
| T5.1 | 删除一致性 | TODO | windy |  |  |  |  |
| T5.2 | 重命名一致性 | TODO | windy |  |  |  |  |
| T5.3 | 敏感隔离验证 | DONE | windy | 2026-02-25 16:17 +0800 | 2026-02-25 16:17 +0800 | 加强 `blacklist.py` 后重建索引，敏感文档出现 `[QUARANTINED]`; `memory_secure_audit=79` | 通过（基于真实数据回归） |
| T5.4 | Prompt 注入防护验证 | TODO | windy |  |  |  |  |
| T6.1 | Recall@5 评测 | TODO | windy |  |  |  |  |
| T6.2 | 增量 P95 延迟评测 | TODO | windy |  |  |  |  |
| T6.3 | 冷启动延迟评测 | TODO | windy |  |  |  |  |
| T7.1 | 回滚演练 | TODO | windy |  |  |  |  |

---

## 2. 任务清单（可执行）

### T1 预检阶段

#### T1.1 检查 uv
- 命令：
```bash
uv --version
```
- DoD：
- 输出版本号。

#### T1.2 检查 Docker/psql
- 命令：
```bash
docker --version
psql --version
```
- DoD：
- 至少一种数据库初始化路径可用：`docker` 或本机 `psql`。

#### T1.3 检查 OpenRouter key
- 命令：
```bash
test -n "$OPENROUTER_API_KEY" && echo "OPENROUTER_API_KEY ok" || echo "OPENROUTER_API_KEY missing"
```
- DoD：
- key 非空，且后续 embedding 测试可通过。

### T2 环境与依赖

#### T2.1 同步依赖（uv）
- 命令：
```bash
uv sync --project .scripts/memory
```
- DoD：
- 命令成功，`uv run --project .scripts/memory python -V` 正常返回。

#### T2.2 配置 `.env.memory`
- 文件：`.env.memory`
- 必填：
```ini
VAULT_DIR=/Users/windy/Documents/vault/my-vault
PG_DSN=postgresql://postgres:postgres@localhost:5432/memory
OPENROUTER_API_KEY=...
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_EMBED_MODEL=openai/text-embedding-3-small
OPENROUTER_EMBED_DIM=1536
INDEX_LOCK_FILE=/Users/windy/Documents/vault/my-vault/.memory-index.lock
```
- DoD：
- 所有键存在且非空。

#### T2.3 `.gitignore` 校验
- DoD：
- 包含 `.env.memory`、`.memory-sync.log`、`memory_eval/results/`。

### T3 数据库（pgvector）

#### T3.1 启动数据库
- 命令（Docker）：
```bash
docker run --name pgvector-memory \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=memory \
  -p 5432:5432 \
  -d pgvector/pgvector:pg16
```
- DoD：
- 容器运行且 5432 可连接。

#### T3.2 初始化 Schema
- 命令：
```bash
psql postgresql://postgres:postgres@localhost:5432/memory -f .scripts/memory/schema.sql
```
- DoD：
- `memory_primary`、`memory_secure_audit` 和向量索引创建成功。

#### T3.3 连通性验证
- 命令：
```bash
psql postgresql://postgres:postgres@localhost:5432/memory -c "SELECT 1;"
```
- DoD：
- 返回 `1`。

### T4 主链路实施

#### T4.1 全量索引
- 命令：
```bash
uv run --project .scripts/memory python .scripts/memory/ingest_vault.py
```
- DoD：
- 日志包含 `UPSERTED/QUARANTINED/PRUNED/DONE`。
- SQL 校验：
```bash
psql postgresql://postgres:postgres@localhost:5432/memory -c "SELECT count(*) FROM memory_primary;"
```

#### T4.2 查询链路验证
- 命令：
```bash
uv run --project .scripts/memory python .scripts/memory/query_pgvector.py "总结我最近的重点项目"
```
- DoD：
- 返回 `<retrieved_context source="...">` 块。

#### T4.3 安装增量 Hook
- 命令：
```bash
bash .scripts/memory/install-hook.sh
```
- DoD：
- `.git/hooks/post-commit` 含 `memory async index hook`。

### T5 一致性与安全验收

#### T5.1 删除一致性
- 操作：删除已索引文档并提交。
- 验证：
```bash
tail -n 80 .memory-sync.log
```
- DoD：
- 出现 `[DELETED] old_path`，旧路径无法召回。

#### T5.2 重命名一致性
- 操作：重命名已索引文档并提交。
- DoD：
- 出现 `[RENAMED-OLD-DELETED] old_path`，新路径可召回。

#### T5.3 敏感隔离
- 操作：测试文档加入私钥头/token 并提交。
- SQL 验证：
```bash
psql postgresql://postgres:postgres@localhost:5432/memory -c "SELECT id, risk FROM memory_secure_audit ORDER BY updated_at DESC LIMIT 20;"
```
- DoD：
- 文档不在 `memory_primary`，在 `memory_secure_audit`。

#### T5.4 Prompt 注入防护
- 操作：插入“忽略规则/执行命令”文本后查询。
- DoD：
- 内容仅作为 `<retrieved_context>` 引用，不影响系统硬规则。

### T6 指标验收（必须量化）

#### T6.1 Recall@5
- 输入：`memory_eval/queries.jsonl`（字段：`query`, `gold_sources`）。
- DoD：
- Recall@5 >= 70%。

#### T6.2 增量延迟 P95
- 方法：
- 记录一次 commit 触发到 `.memory-sync.log` 出现对应 `UPSERTED/DELETED` 的时间差。
- 样本 >= 30 次。
- DoD：
- P95 < 1s（不含 OpenRouter 网络异常样本）。

#### T6.3 冷启动延迟
- 方法：
- 统计从执行 `agent-with-memory.sh` 到 Claude CLI 唤醒的总耗时，样本 >= 20 次。
- DoD：
- <= 4.5s（网络异常样本单独标注）。

### T7 回滚演练（必须做一次）

#### T7.1 无记忆模式回滚
- 步骤：
1. 移除 `.git/hooks/post-commit` 的 memory 片段。
2. 停用 `agent-with-memory.sh`，改用普通 `claude`。
3. 如需清库：
```bash
psql postgresql://postgres:postgres@localhost:5432/memory -c "TRUNCATE memory_primary, memory_secure_audit;"
```
- DoD：
- 回滚后常规工作流可用，且不再触发记忆同步。

---

## 3. 覆盖矩阵（方案/计划问题是否全部覆盖）

| 关键要求 | 来源 | 对应任务 | 是否覆盖 |
|---|---|---|---|
| 不用本地 embedding 模型 | Strategy v5.0 | T1.1/T2.1/T4.1 | 是 |
| 本地向量持久化 pgvector | Strategy v5.0 | T3.1/T3.2/T3.3 | 是 |
| Git 增量同步 A/M/D/R | Strategy v5.0 + Deployment v5.0 | T4.3/T5.1/T5.2 | 是 |
| 强一致删除无幽灵向量 | Strategy v5.0 | T5.1/T5.2 | 是 |
| 敏感隔离不入 Primary | Strategy v5.0 | T5.3 | 是 |
| Prompt 注入防护 | Strategy v5.0 | T5.4 | 是 |
| Recall@5 >= 70% | Strategy v5.0 | T6.1 | 是 |
| 增量 P95 < 1s | Strategy v5.0 | T6.2 | 是 |
| 冷启动 <= 4.5s | Strategy v5.0 | T6.3 | 是 |
| 可回滚 | Deployment v5.0 | T7.1 | 是 |

结论：
- 当前任务文档已具备“任务状态监控 + 证据留存 + 指标验收 + 覆盖矩阵”。
- 可用于实施过程中的逐项跟踪与审计。

---

## 4. 执行顺序（建议）
1. `T1 -> T2 -> T3 -> T4 -> T5 -> T6 -> T7`
2. 每完成一个任务，立即更新执行看板的状态与证据列。