Agent 现在的记忆实现，不是说只弄个向量数据库就完事了。向量库只能解决语义相似度检索，但 Agent Memory 还需要时间、版本、关系、来源、冲突、状态、工具轨迹和生命周期管理。

RAG

在 Agent 场景里RAG 不是把资料丢进向量数据库，接下来相似度搜索就完事了。一个真正可用的 RAG 至少包含下面的流程：

使用者痛点：仅使用向量搜索时经常出现“检索不到关键代码片段”或“返回内容与查询意图不匹配”。

你需要让 AI 帮你细化 RAG 链路，例如加入「关键词索引 BM25」来弥补向量搜索的不足。其实，

真实项目里最好不要只选一种检索方式。再看例如使用者问，

If only vector search is used,you may get semantically related results like “Android 内存调整”。but miss exact key:

memory.highmemory.swap.maxmemory.eventspmgd/config.json

需求上可以要求 AI：

• 向量检索用于语义召回；老实说，
• BM25 用于关键词/代码符号/错误码/专有名词召回；
• 两路结果合并去重并归一化打分；话说回来，
• 使用 reranker 对候选片段重排；
• 返回结果必须带 source、chunk_id、score、metadata，以便引用和排查。

Chunking 比向量库更关键

使用者痛点：文档切块不合理导致检索命中率低。甚至上下文断裂，使得答案缺乏连贯性。

Chunking 把文档切成适合检索的小片段。常见方式包括按章节、按段落或按函数/类切分。怎么说呢，

第 1 块：Android 引入了 PMGD。它可以通过...
第 2 块：/vendor/etc/pmgd/config.json 配置 memory.high...

正确做法是保持父子层级：

- 小 chunk 用于搜索：
- config.json 配置
- memory.high
- memory.events
- 父 chunk 用于回答：
- 整个 PMGD 小节

You can ask AI to:

• 代码按函数/类切；
• 每个 chunk 保留 parent_id；
• 检索时用小 chunk 命中；其实，
• 回答时返回 parent chunk 或相邻 chunk；
• tag each chunk with source、heading_path、created_at、updated_at、token_count。老实说，

Metadata 也很关键

使用者痛点：No metadata → inability to filter results → noisy answers and higher hallucination risk.

{
"source": "android_17_memory.md","type": "technical_note"。"created_at": "--","section": "PMGD","tags":,"language": "zh-CN","project": "Android"
}

If you need to filter by date,project,or document type,metadata is essential.

You can tell AI:

RAG 数据库不要只存 text 和 embedding。每个 chunk 必须保存 metadata，包括 source、title、section、tags、
language、created_at、updated_at、doc_type、project、is_archived。检索时支持 metadata filter。

Reranker：检索召回之后还要重排

User pain point: Top‑K from vector/BM25 often includes irrelevant items;without reranking final answer drifts.

E.g.,query “Flutter iOS SPM migration publicHeadersPath config? 话说回来，” might retrieve generic Flutter docs but miss exact snippet containing “publicHeadersPathPackage.swift”. A reranker pushes precise match to top.

检索流程需要有 rerank 阶段。老实说，先用 hybrid search 召回 N 条候选。再用 reranker 重排，只给 LLM Top M 条。不要直接把向量检索 TopK 原样塞进 prompt。

Query Rewrite

User pain point:The original user query often contains noise or ambiguous terms,leading to poor retrieval results.

The agent should rewrite query into multiple sub‑queries:

• a natural‑language query;老实说，
• a keyword‑focused query;
• An English technical term query;
.
• a code/API/config name query;
.
• a synonym query.
.

实现 RAG 时需要 query rewrite。不要直接用使用者原句检索。请生成 N 个 query：
- 原始自然语言；- 关键词，- 英文技术术语；- 代码/API/配置名；- 同义表达，最终合并检索结果。不过，

状态流转

User pain point:Lack of explicit state leads to random jumps。causing low success rates and hard‑to‑debug flows.

IDLE → COLLECT_REQUIREMENTS → RESEARCH → OUTLINE → DRAFT → REVIEW → REVISE → FINAL
每个状态都有明确输入/输出，只有满足条件才允许转移。非法转移触发错误处理或人工干预。

Workflow：复杂任务不要靠 Prompt 编排全部逻辑

A workflow breaks a big task into deterministic steps with clear I/O and failure handling.

读取 README ↓识别项目目标 ↓读取 package/build 配置 ↓分析目录结构 ↓找主要入口
↓检查最近 commit ↓检查 issue/PR ↓输出结论

• No giant prompt;design a step‑by‑step flow.
• Eeach step defines input,output。retry policy and optional human confirmation.
Persist intermediate artifacts for replay and debugging.

Planner / Executor 架构

p> User Pain Point: A single LLM doing planning + execution often mixes responsibilities leading to hallucinations or unsafe actions.

p> Split responsibilities:

• Planner – only creates a plan .
• Executor – executes one atomic step according to plan.
• Verifier – checks wher result satisfies acceptance criteria.

pre> 请采用 Planner / Executor / Verifier 架构： - Planner 拆解任务，不调用工具；- Executor 执行当前步骤，不擅自改变目标；- Verifier 检查结果是否满足验收条件；- 若失败，回到对应步骤重试，而不是从头开始。

Tool Schema

p> User Pain Point: Vague tool definitions cause runtime errors and security risks.

p> 每个 tool 必须提供完整 JSON schema，包括 name 、 description 、 input 参数类型 、 output 格式 、 error codes 、 权限等级 、 是否幂等 等信息。

pre> { 再看"name"，"searchdocuments","description":"Hybrid retrieval over indexed docs","input":{"query":"string","filters":{"project":"string","doctype":"string"},"top_k":"number"}。"output":{"chunks":} }

h3 id=tool-routing>Tool Routing p> User Pain Point: Letting LLM pick any tool arbitrarily leads to unnecessary calls or security violations.

p> Design a router that decides when to invoke which tool based on intent categories .

pre> • 必须查 RAG 时走 retriever；• 必须查询网页时走 web_search；不过，• 可直接回答时跳过工具；• 调用代码分析工具前先确认语言类型；话说回来，• 高风险操作必须人工确认。

Memory

Procedural memory ="存储写作流程等可执行步骤。"，=""