windy/my-vault
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
410167d3b4b51d806268376a1e7e9934c5b67eea
my-vault/04_Archive/agent-memory-2026-02/AGENT_MEMORY_IMPLEMENTATION_TASKS_2026-02-25.md
T

10 KiB
Raw Blame History

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 删除一致性 DONE windy 2026-02-25 16:25 +0800 2026-02-25 16:25 +0800 incremental_ingest --changes-file 触发 D 后日志出现 [DELETED] ...memory-consistency-test.md；SQL remain=0 通过（无提交模拟验证）
T5.2 重命名一致性 DONE windy 2026-02-25 16:26 +0800 2026-02-25 16:27 +0800 日志出现 [RENAMED-OLD-DELETED] old + [UPSERTED] new；SQL old_remain=0,new_exist=1（后续已清理测试文档） 通过（无提交模拟验证）
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 注入防护验证 DONE windy 2026-02-25 16:27 +0800 2026-02-25 16:28 +0800 检索结果始终包裹在 <retrieved_context source=\"...\">...</retrieved_context>；注入样例文档已回收删除 通过
T6.1 Recall@5 评测 DONE windy 2026-02-25 16:28 +0800 2026-02-25 16:28 +0800 memory_eval/queries.jsonl(10样本) 评测输出 hits=9 recall_at_5=0.9；结果文件 memory_eval/results/recall_at_5_2026-02-25.json 达标（>=70%）
T6.2 增量 P95 延迟评测 DONE windy 2026-02-25 16:28 +0800 2026-02-25 16:29 +0800 35 次 M 样本（网络异常 0）结果：p95=1.4013s p50=1.1469s；结果文件 memory_eval/results/incremental_latency_p95_2026-02-25.json 已量化，但未达标（目标 <1s）
T6.3 冷启动延迟评测 BLOCKED windy 2026-02-25 16:29 +0800 2026-02-25 16:29 +0800 agent-with-memory.sh 与 claude -p 在自动化测量中超时（>20s / >60s） 当前环境无法稳定完成 20 次冷启动量化
T7.1 回滚演练 DONE windy 2026-02-25 16:29 +0800 2026-02-25 16:37 +0800 自动演练 + 手工复核：install-hook.sh 后 rg 命中 hook 片段，test -x 通过，tail 显示入口完整 非破坏性演练通过（已恢复工作态）

2. 任务清单（可执行）

T1 预检阶段

T1.1 检查 uv

  • 命令：
uv --version
  • DoD：
  • 输出版本号。

T1.2 检查 Docker/psql

  • 命令：
docker --version
psql --version
  • DoD：
  • 至少一种数据库初始化路径可用：docker 或本机 psql。

T1.3 检查 OpenRouter key

  • 命令：
test -n "$OPENROUTER_API_KEY" && echo "OPENROUTER_API_KEY ok" || echo "OPENROUTER_API_KEY missing"
  • DoD：
  • key 非空，且后续 embedding 测试可通过。

T2 环境与依赖

T2.1 同步依赖（uv）

  • 命令：
uv sync --project .scripts/memory
  • DoD：
  • 命令成功，uv run --project .scripts/memory python -V 正常返回。

T2.2 配置 .env.memory

  • 文件：.env.memory
  • 必填：
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）：
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

  • 命令：
psql postgresql://postgres:postgres@localhost:5432/memory -f .scripts/memory/schema.sql
  • DoD：
  • memory_primary、memory_secure_audit 和向量索引创建成功。

T3.3 连通性验证

  • 命令：
psql postgresql://postgres:postgres@localhost:5432/memory -c "SELECT 1;"
  • DoD：
  • 返回 1。

T4 主链路实施

T4.1 全量索引

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

T4.2 查询链路验证

  • 命令：
uv run --project .scripts/memory python .scripts/memory/query_pgvector.py "总结我最近的重点项目"
  • DoD：
  • 返回 <retrieved_context source="..."> 块。

T4.3 安装增量 Hook

  • 命令：
bash .scripts/memory/install-hook.sh
  • DoD：
  • .git/hooks/post-commit 含 memory async index hook。

T5 一致性与安全验收

T5.1 删除一致性

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

T5.2 重命名一致性

  • 操作：重命名已索引文档并提交。
  • DoD：
  • 出现 [RENAMED-OLD-DELETED] old_path，新路径可召回。

T5.3 敏感隔离

  • 操作：测试文档加入私钥头/token 并提交。
  • SQL 验证：
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. 如需清库：
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. 每完成一个任务，立即更新执行看板的状态与证据列。
Reference in New Issue View Git Blame Copy Permalink