309 lines
9.8 KiB
Markdown
309 lines
9.8 KiB
Markdown
---
|
||
title: "feat: AgentKit 分层记忆系统 — SOUL/USER/MEMORY/DAILY 注入"
|
||
status: completed
|
||
created: 2026-06-08
|
||
plan_type: feat
|
||
depth: 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 无法：
|
||
1. 拥有持久人格（名字、性格、说话方式）
|
||
2. 记住用户信息（称呼、习惯、职业）
|
||
3. 跨会话保留工作笔记
|
||
4. 回顾近期决策和对话摘要
|
||
|
||
虽然已有 `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 场景无并发问题 |
|