Agent 记忆与分层检索
在自主 AI Agent 执行多步工程任务时，经常会出现两种典型故障：
- 目标漂移与代偿性过度设计（Goal Drift & Compensatory Over-Abstraction）：任务进行到中途，Agent 遗失了人类原始意图与硬性约束，转而通过构建过度复杂的抽象、中间适配层和脱离需求的平台化架构来进行代偿。
- Context 暴饮暴食与重复碎片化（Context Window Bloat & Duplicate Fragmentation）：由于缺乏精准的行级检索手段，Agent 倾向于将数百行的大文件全量塞入 Prompt，洗刷掉核心系统指令；而在撰写文档时，由于无法准确定位已有 Canonical 路由，导致重复创建孤岛文档。
构建高可靠 Agent 不能单纯依赖扩大上下文窗口，而需要建立一套多层级认知与检索架构（Multi-Tiered Cognitive & Retrieval Hierarchy），将高层决策对齐与底层代码/文档语法探索彻底解耦。
四层认知分层金字塔
1. L0：意图与对齐层（Why & What）
- 承载体：人类裁判 +
Basic Memory（或受控项目 Alignment 规范文档）。 - 核心实体：
Project、Decision、Boundary、Phase。 - 职责：界定项目“正在做什么”、“坚决不做什么”以及“何时停止”。代表人类权威共识，绝不被常规工具循环或临时日志反向污染。
2. L1：领域概念花园（跨项目复用）
- 承载体：语义 Markdown 知识库（如
QMD、Obsidian 知识网络）。 - 核心实体：
Concept Note、Source Reference、Methodology。 - 职责：沉淀跨项目的普遍原理（例如：量化研究与生产运行隔离、事件驱动架构）。在需要方法论输入或设计选型时按需加载。
3. L2：语法与代码实体层（Where & How）
- 承载体：具备 AST 感知能力的混合检索引擎（如
zvec-grep(zg)、Ripgrep）。 - 核心实体：
Class、Function、Docstring、Markdown Heading、Code Slice。 - 职责：在亚秒级 CPU 延迟下外科手术式定位代码块与行号。输出专为节省 Token 设计的极简格式（约 80 tokens），杜绝上千 Token 的全文件 dump。
4. L3：瞬时工作记忆（Now）
- 承载体：模型的当前活跃上下文窗口与 Turn 历史。
- 职责：执行当下单一补丁，运行离线验证，输出结果并立即停止。
工具与实体粒度对比矩阵
| 评估维度 | Basic Memory | QMD | zvec-grep (zg) |
|---|---|---|---|
| 主要定位 | 人机决策与认知对齐真值源 | 跨项目理论与来源证据库 | AST 符号与行号精准定位器 |
| 纳管实体 | Decision, Boundary, Milestone | Concept, Theory, Paper Citation | Class, Function, Heading Slice |
| 检索引擎 | 结构化图 / 关系型 MCP | 混合向量 + BM25 文本检索 | AST 语法解析 + model2vec (CPU) + FTS |
| Token 开销 | 约 1,500 – 3,000 tokens（单篇项目 Alignment） | 约 1,000 – 2,000 tokens（单篇完整概念） | 约 80 tokens（仅输出文件、行号与符号签名） |
| 写入权限 | 仅限人类显式验收批准 | 阶段性整理与人工审阅 | 只读本地缓存（Git 忽略，零持久化负担） |
| 典型归属 | knowledge/projects/*.md | knowledge/concepts/*.md | 活动仓库源码与文档（如 Finance/, my-website/） |
外科手术式端到端协同流
Agent 不再靠大范围扫读盲猜，而是严格遵循低 Token 预算流水线：
工程实践防腐准则
1. 实体前置探查法则（Entity-First Probe）
“在新建任何文件、类或路由之前，必须证明库中不存在同语义的已有实体。”
- 在文档站点（如 Docusaurus）：
编写或构思任何主题前，先执行：
如果已有 Canonical 页面或章节匹配，就地扩写或建立双向链接，绝不新建重复文档分裂知识网络。npx @zvec/zvec-grep query "<主题或实体关键词>" -g 'docs/**' --limit 3
- 在源码工程库：
在编写新算法前，先探查现有工程，复用既有的纯算子模块（例如独立的
metrics.py），避免重复造轮子。
2. 极简定向读取（Surgical Read）
- 禁止无目的地
cat或全文读取超过 100 行的文件； - 依据
zg输出的精准坐标，限定读取范围在[StartLine, EndLine]； - 将上下文消耗严格压缩在当前修改切实相关的行数内。
3. 单向依赖与防污染边界
- 高层约束底层，底层不污染高层：
- Basic Memory 中的宏观战略约束代码编写；
- 严禁将底层临时运行日志、单机测试计数或 CLI 工具说明写进长期知识库；
- 仓库专属的检索习惯与工具命令，仅保留在对应仓库的
AGENTS.md中，就地生效，绝不外溢。
核心工具官方开源仓库与文档
- L0 意图与红线：Basic Memory (GitHub) | PyPI
- L1 概念花园：QMD (GitHub) | NPM
- L2 AST 与代码搜索：zvec-grep (GitHub) | NPM