fischer-agentkit/2026-06-08-016-feat-agentkit-layered-memory-plan.md at dddcbd24e3963084a913b97b2ceca00b2d43ffba

9.8 KiB

Raw Blame History

title	status	created	plan_type	depth
feat: AgentKit 分层记忆系统 — SOUL/USER/MEMORY/DAILY 注入	completed	2026-06-08	feat	standard

Summary

为 AgentKit 实现分层记忆注入系统，参考 Hermes/OpenClaw 架构，在每次会话启动时将 SOUL.md（Agent 人格）、USER.md（用户档案）、MEMORY.md（Agent 工作笔记）、DAILY.md（最近日志）注入 system prompt，并提供 MemoryTool 让 Agent 在对话中读写记忆。采用 TDD 方式开发。

Problem Frame

当前 agentkit chat 的 system prompt 是硬编码的一句话，Agent 无法：

拥有持久人格（名字、性格、说话方式）
记住用户信息（称呼、习惯、职业）
跨会话保留工作笔记
回顾近期决策和对话摘要

虽然已有 memory/ 模块（Working/Episodic/Semantic），但这些是面向 Pipeline 编排的底层记忆，不是面向 Chat 场景的"人格+档案+笔记"注入。

Requirements

R1: SOUL.md — Agent 人格定义，每次会话必须加载
R2: USER.md — 用户档案，每次会话必须加载
R3: MEMORY.md — Agent 工作笔记，每次会话必须加载，Agent 可通过工具修改
R4: DAILY.md — 最近 2 天日志，每次会话自动加载，Agent 可通过工具追加
R5: MemoryTool — Agent 可在对话中 add/replace/remove 记忆条目
R6: 文件存储在 ~/.agentkit/ 目录下，首次运行自动创建默认 SOUL.md
R7: 容量上限 — SOUL ~2000 字符、USER ~1400 字符、MEMORY ~2200 字符、DAILY ~1000 字符/天
R8: 注入方式 — 会话开始时一次性注入 system prompt，会话内不变（利于 KV 缓存）
R9: 与现有 agentkit chat 命令集成

Key Technical Decisions

KTD1: 记忆文件格式 — Markdown sections

每个 .md 文件使用 ## Section 格式组织内容，方便 Agent 通过 MemoryTool 的 replace 操作精确替换某个 section，而非重写整个文件。

## 身份
我是小王，一个专业的 AI 助手。

## 性格
友好、耐心、注重细节

## 说话方式
简洁专业，偶尔使用比喻

KTD2: 注入格式 — 分段注入 system prompt

将记忆内容作为 system prompt 的结构化段落注入，每段用明确的标记分隔：

<agent-identity>
[SOUL.md content]
</agent-identity>

<user-profile>
[USER.md content]
</user-profile>

<agent-notes>
[MEMORY.md content]
</agent-notes>

<recent-activity>
[DAILY.md content]
</recent-activity>

[原始 system prompt 或默认指令]

KTD3: MemoryTool 操作模型 — section 级别 CRUD

memory_add(section, content) — 追加内容到指定 section（不存在则创建）
memory_replace(file, section, old_text, new_text) — 精确替换 section 内的文本
memory_remove(file, section) — 删除整个 section
memory_read(file) — 读取整个文件内容

file 参数: soul | user | memory | daily

KTD4: 日志自动生成 — 会话结束时摘要

会话结束时（用户 /quit 或 Ctrl+C），自动调用 LLM 生成当天日志摘要追加到 DAILY.md。保留最近 2 天日志，更早的自动归档。

KTD5: 存储路径 — `~/.agentkit/memories/`

~/.agentkit/
├── SOUL.md              # Agent 人格
├── memories/
│   ├── USER.md          # 用户档案
│   ├── MEMORY.md        # 工作笔记
│   └── daily/
│       ├── 2026-06-07.md
│       └── 2026-06-08.md
└── agentkit.yaml        # 配置文件（已存在）

Implementation Units

U1. MemoryFile — 记忆文件读写与容量管理

Goal: 实现记忆文件的读写、容量限制、section 级别操作

Dependencies: None

Files:

src/agentkit/memory/profile.py — MemoryFile 类
tests/unit/test_memory_profile.py — 测试

Approach:

MemoryFile 类：封装单个 .md 文件的读写、section 解析、容量检查
read() / write() — 读写整个文件
read_section(name) / add_section(name, content) / replace_section(name, old, new) / remove_section(name) — section 级别操作
trim_to_budget(char_budget) — 超出容量时从末尾裁剪（保留前面的 section）
文件不存在时返回空字符串，不抛异常

Execution note: TDD — 先写测试再实现

Test scenarios:

读取不存在的文件返回空字符串
写入并读回完整内容
解析 ## Section 格式，read_section 返回指定 section 内容
add_section 追加新 section
replace_section 精确替换 section 内文本
remove_section 删除指定 section
超出 char_budget 时 trim_to_budget 裁剪
空文件 read_section 返回空

Verification: 所有测试通过

U2. MemoryStore — 多文件记忆管理器

Goal: 管理 SOUL/USER/MEMORY/DAILY 四类记忆文件，提供统一的加载和注入接口

Dependencies: U1

Files:

src/agentkit/memory/profile.py — MemoryStore 类（同文件）
tests/unit/test_memory_profile.py — 追加测试

Approach:

MemoryStore(base_dir) — 接受 ~/.agentkit 路径
load_all() — 加载所有记忆文件，返回 MemorySnapshot dataclass
build_system_prompt(snapshot, base_prompt) — 将记忆注入 system prompt
get_file(file_key) — 返回指定 MemoryFile（file_key: soul/user/memory/daily）
load_daily_logs(days=2) — 加载最近 N 天日志
archive_old_dailies(days=2) — 归档超过 N 天的日志
ensure_defaults() — 首次运行创建默认 SOUL.md
MemorySnapshot dataclass: soul, user, memory, daily, total_chars

Execution note: TDD

Test scenarios:

MemoryStore 初始化，目录不存在时自动创建
load_all() 返回 MemorySnapshot
build_system_prompt() 正确注入所有段落
build_system_prompt() 无记忆文件时只返回 base_prompt
ensure_defaults() 创建默认 SOUL.md
load_daily_logs() 加载最近 2 天日志
archive_old_dailies() 归档旧日志
容量超限时 build_system_prompt 仍能工作（trim）

Verification: 所有测试通过

U3. MemoryTool — Agent 可调用的记忆操作工具

Goal: 实现 Agent 在对话中读写记忆的工具

Dependencies: U1, U2

Files:

src/agentkit/tools/memory_tool.py — MemoryTool 类
tests/unit/test_memory_tool.py — 测试

Approach:

继承 Tool 基类
memory_add(file, section, content) — 追加内容
memory_replace(file, section, old_text, new_text) — 替换内容
memory_remove(file, section) — 删除 section
memory_read(file) — 读取文件
file 参数限定为 soul | user | memory | daily
操作后自动 trim 到容量上限
返回操作结果和当前文件内容摘要

Execution note: TDD

Test scenarios:

memory_add 创建新 section
memory_add 追加到已有 section
memory_replace 精确替换文本
memory_replace old_text 不存在时返回错误
memory_remove 删除 section
memory_read 返回文件内容
无效 file 参数返回错误
操作后内容不超容量上限

Verification: 所有测试通过

U4. Chat 集成 — 记忆注入 + MemoryTool + 日志生成

Goal: 将记忆系统集成到 agentkit chat 命令

Dependencies: U2, U3

Files:

src/agentkit/cli/chat.py — 修改
tests/unit/test_chat_memory_integration.py — 测试

Approach:

_chat_async() 启动时：
1. 初始化 MemoryStore(base_dir=~/.agentkit)
2. 调用 ensure_defaults() 创建默认文件
3. load_all() 加载记忆
4. build_system_prompt(snapshot, base_prompt) 构建完整 system prompt
5. 将 MemoryTool(memory_store) 加入 tools 列表
会话结束时：
1. 调用 LLM 生成当天对话摘要
2. 追加到 DAILY.md
3. 归档旧日志
/clear 命令不清除记忆文件，只清除会话历史

Execution note: TDD

Test scenarios:

chat 启动时自动加载记忆注入 system prompt
无记忆文件时使用默认 SOUL.md
MemoryTool 在对话中可用
会话结束时生成日志摘要
/clear 不影响记忆文件
记忆跨 /clear 会话持久化

Verification: 所有测试通过，手动 agentkit chat 验证

U5. Onboarding 集成 — 首次引导创建 SOUL.md

Goal: 在 onboarding 向导中增加 Agent 人格配置步骤

Dependencies: U2

Files:

src/agentkit/cli/onboarding.py — 修改
tests/unit/test_onboarding.py — 追加测试

Approach:

onboarding 最后一步增加可选的 Agent 人格配置：
- Agent 名字（默认 "AgentKit"）
- 性格描述（默认 "专业、友好、注重细节"）
- 说话方式（默认 "简洁清晰"）
写入默认 SOUL.md
可跳过（使用默认值）

Execution note: TDD

Test scenarios:

onboarding 生成默认 SOUL.md
自定义名字写入 SOUL.md
跳过时使用默认值

Verification: 所有测试通过

Scope Boundaries

In Scope

SOUL/USER/MEMORY/DAILY 四层记忆文件
MemoryFile section 级别 CRUD
MemoryStore 统一加载和注入
MemoryTool Agent 可调用工具
Chat 命令集成
Onboarding 集成
日志自动生成

Out of Scope

向量检索记忆（已有 EpisodicMemory）
Redis/PostgreSQL 后端（已有 WorkingMemory/SemanticMemory）
多 Agent 共享记忆（后续）
记忆版本控制（后续）
记忆加密（后续）

Deferred to Follow-Up Work

记忆导入/导出命令
记忆搜索（在大量笔记中搜索）
与 EpisodicMemory 的整合（将 DAILY 日志同步到 Episodic）

Open Questions

None — 所有设计决策已在 KTD 中明确。

Risks & Mitigations

风险	缓解措施
system prompt 过长占用 token	容量上限 + trim_to_budget
Agent 恶意修改 SOUL.md	SOUL.md 可设为只读（后续），当前信任 Agent
日志文件无限增长	archive_old_dailies 自动归档，保留最近 2 天
文件并发写入冲突	单进程 chat 场景无并发问题

9.8 KiB Raw Blame History Unescape Escape

Summary

Problem Frame

Requirements

Key Technical Decisions

KTD1: 记忆文件格式 — Markdown sections

KTD2: 注入格式 — 分段注入 system prompt

KTD3: MemoryTool 操作模型 — section 级别 CRUD

KTD4: 日志自动生成 — 会话结束时摘要

KTD5: 存储路径 — ~/.agentkit/memories/

Implementation Units

U1. MemoryFile — 记忆文件读写与容量管理

U2. MemoryStore — 多文件记忆管理器

U3. MemoryTool — Agent 可调用的记忆操作工具

U4. Chat 集成 — 记忆注入 + MemoryTool + 日志生成

U5. Onboarding 集成 — 首次引导创建 SOUL.md

Scope Boundaries

In Scope

Out of Scope

Deferred to Follow-Up Work

Open Questions

Risks & Mitigations

9.8 KiB

Raw Blame History

KTD5: 存储路径 — `~/.agentkit/memories/`