QDKT构建一个可复用的 Agent 记忆管理框架

一、核心目标与系统定位

本次方案规划旨在为Agent（AI智能体）构建一套外挂式记忆管理系统，实现会话信息的自动抽取、结构化存储与高效检索，从而解决Agent在多轮对话中上下文丢失、记忆无法跨会话复用的问题。

系统定位：独立于Agent本体运行的记忆外挂，不干扰Agent当前上下文，可适配多种Agent框架（如爱马仕/Harness、Codex、OpenClose等）。

二、记忆系统的触发机制

系统支持三种触发方式，按优先级推荐如下：

1. 自动触发（Hooks/生命周期钩子）------首选方案

核心概念：利用Agent框架内置的Hooks（钩子）机制，在Agent生命周期的关键事件节点自动触发记忆处理流程。
Hooks类型：
- Command类型：执行脚本或终端指令（如Python脚本），与MCP的command格式类似。
- Prompt类型：触发后向Agent发送特定提示词（爱马仕支持，Codex不支持）。
典型事件节点：
- 会话开始（session start）
- 会话结束（on session end）------最推荐，因此时会话已落库且异步非阻塞，不影响主流程
- 用户提交消息（user prompt submit）
- 工具调用前/后（pre/post tool use）
- 子Agent启动（subagent start）
- 权限请求（permission request）
框架差异：
- Codex ：默认开启Hooks，支持约10个事件，配置在codex.toml中，需创建hooks.json定义具体规则。
- 爱马仕（Harness）：支持网关级、插件级（plug hooks）、终端级（shell hooks）三类，插件级最常用，支持在消息发送前后注入内容。
- OpenClose：支持自定义事件绑定，事件类型最灵活。
- Workbody：客户端不支持，但Codebody CLI支持。

2. 定时触发------兜底方案

使用Cron定时任务（如每小时扫描一次），检查数据库中未正常触发Hooks的会话（如进程崩溃导致的异常中断）。
注意：避免使用Agent本体执行定时任务，因为会创建新会话导致无限循环。应使用外挂脚本进程独立运行。

3. 手动触发------辅助方案

配置Skill或指令，引导Agent执行记忆记录，适用于用户主动要求"记住某事"的场景。
注意：不适用于批量会话分析，同样会导致会话循环问题。

三、运行模式：外挂式优先

模式一：融合模式（内循环）

抽取的记忆直接写入Agent上下文（如系统提示词），伴随对话实时生效。
缺点：依赖开源项目才能深度改造；会污染当前会话上下文，干扰Agent正常工作。

模式二：外挂模式（强烈推荐）

架构：Agent是Agent，记忆是记忆，完全解耦。
实现：通过Hooks触发外部Python脚本，脚本调用LLM API完成信息抽取，产出文档存入本地文件系统。
优势：
- 不干扰Agent当前上下文
- 跨Agent框架通用
- 使用独立的大模型资源，避免循环依赖
- 存储与检索完全独立，可控性高

四、最小可行产品（MVP）架构

核心组件

触发层：Hooks（会话结束事件）+ 定时扫描（兜底）
处理层：
- 会话清洗器：从数据库提取原始会话，过滤噪音（如工具返回的冗余信息），保留User与Assistant的content及工具名称，按轮次组织。
- 记忆提取器：调用LLM API，从清洗后的会话中提取结构化记忆（用户记忆、任务记忆、知识记忆、技能记忆）。
- 记忆写入器：以Markdown格式分类存储。
检索层：基于关键词的检索接口（如grep封装），支持Agent通过Skill召回记忆。
使用规范：为Agent提供SOP/Skill，说明如何调用记忆数据。

数据流

plain

复制代码

Agent会话结束 → Hooks触发 → Session ID写入待处理队列（.pending文件/轻量表） 
→ 异步消费 → 抽取会话内容 → 清洗 → LLM分析提取 → 结构化输出 
→ 增量合并 → 写入本地MD文件 → Agent通过关键词检索召回

五、以爱马仕为例的具体实现

1. 数据源与会话存储

爱马仕在2025年6月5日后将会话数据存储在state.db（SQLite数据库）中。
核心表结构：
- sessions表：存储会话ID、标题、摘要等基础信息。
- messages表：存储每个会话的完整对话轮次，通过sessionID关联。
提取方式：可直接使用SQL查询，或让Agent基于Skill自检存储路径。

2. 会话清洗策略

噪音分析：工具输出通常占90%以上，用户输入仅占1%-3%，需大幅压缩。
清洗规则：
- 保留：用户输入、助手回复、工具调用名称。
- 剔除：工具执行的详细返回信息、系统级报错（除非关键）。
- 输出格式：按轮次（Turn N）组织，包含时间戳、原始输入、决策摘要、工具返回概要、轮次间隔时长。

3. 记忆提取与结构化

LLM任务：将清洗后的会话发给大模型，提取高价值、低噪音的记忆。
输出格式（JSON）：每条记忆包含：
- content：具体内容
- confidence：置信度（0-1）
- source_turn：来源轮次（便于溯源）
- memory_type：记忆类型（user/task/knowledge/skill）
- tags：标签
增量合并策略：附带当前记忆快照，要求LLM做增量合并而非重复输出，避免长期运行后的数据膨胀。

4. 记忆存储结构（Markdown）

目录设计：
- index.md：总索引
- user/：用户信息
- tasks/：任务信息
- memories/：通用记忆
- skills/：技能记忆
- sessions/：原始会话快照（溯源用）
单篇文档格式：
- 元数据区：创建时间、关联session、类型、标签
- 结构化摘要行 ：固定格式（如[状态] | [类型] | [标签] | 一句话核心内容），确保机器可读且grep友好。
- 详情区：展开描述，支持related字段关联其他记忆。
检索友好性：单行摘要足够短，批量grep结果不超过几十行，不撑爆上下文；Agent拿到grep结果后可选择性展开详情。

5. 检索与召回

检索方式：基于关键词的grep检索（或封装脚本），暂不建议使用Embedding向量检索（慢、不精准、需分段处理）。
注入策略 ：利用爱马仕的pre tool use或消息发送前钩子，根据用户当前输入动态检索相关记忆并注入上下文，而非全量注入index。

六、关键设计策略与优化建议

1. 队列机制

维护一个待处理队列 （如.pending文件或SQLite表），将Hooks触发的Session ID先入队，再由处理管线异步消费。
作用：削峰填谷，避免内存撑爆或带宽不足导致数据丢失，确保程序丝滑可控运行。

2. 兜底机制

Hooks依赖Agent进程，若进程崩溃则无法触发。需配合定时扫描任务，对比已处理记录日志，筛选遗漏会话重新入队。

3. 规则迭代策略（生长式优化）

对于记忆提取、精选规则等难以一次性定义清晰的策略，建议采用人机协同迭代：
- 先让AI输出一版基础规则；
- 提供人工标注入口（如精选/不精选），让AI学习用户偏好；
- 将学习到的规律自动追加到规则库，实现规则的持续生长。

4. 记忆冲突与更新

当用户偏好变化或信息冲突时，需设计时间衰减机制 或置信度覆盖机制，由LLM判断合并策略，而非简单追加。

5. 多用户支持

个人版：单用户，无需隔离。
企业版：需支持多用户隔离，按用户ID分库存储。

七、待对齐与深化的问题

记忆提取选用哪个LLM？（需根据成本与效果权衡）
增量合并的具体规则：先规则去重再LLM合并，还是完全交给LLM判断？
动态注入时机：是仅注入index常驻记忆，还是根据当前消息动态检索后注入？
Session追踪方式：Hooks传递Session ID vs 处理层直接扫描数据库？
记忆冲突时的更新与失效策略：如何设计时间衰减与权重调整？
是否需要Embedding检索？（当前结论：没必要，关键词检索更轻量高效）

八、实施路径建议

方案对齐 ：先与AI讨论输出一版不含代码的项目方案文档，确认架构与流程。
文档准备：整理目标Agent的Hooks文档（如爱马仕9000字精简版）、数据库Schema、数据清洗调研报告。
分步开发：
- 第一步：实现Hooks触发 + 会话清洗脚本
- 第二步：实现LLM记忆提取与Markdown写入
- 第三步：实现检索封装与Agent使用规范（Skill/SOP）
持续迭代：上线后通过人工标注反馈优化提取规则与分类策略。

总结：本方案的核心思路是**"Hooks触发 + 外挂脚本 + LLM抽取 + 本地MD存储 + 关键词检索"**，以最轻量的方式实现Agent的跨会话记忆能力，同时保持系统解耦与可扩展性。