持久化记忆
KOPI AI AGENT 拥有有限且经过整理的记忆,可在多个会话之间持久保存。这使其能够记住你的偏好、你的项目、你的环境,以及它学到的内容。
工作原理
Agent 的记忆由两个文件组成:
| 文件 | 用途 | 字符上限 |
|---|---|---|
| MEMORY.md | Agent 的个人笔记 — 环境信息、约定、学到的知识 | 2,200 字符(约 800 tokens) |
| USER.md | 用户资料 — 你的偏好、沟通风格、期望 | 1,375 字符(约 500 tokens) |
这两个文件都存储在 ~/.kopi/memories/ 中,并在会话开始时作为冻结快照注入 system prompt。Agent 通过 memory 工具管理自己的记忆 — 它可以添加、替换或删除条目。
字符上限可保持记忆的聚焦。记忆不会自动压缩:当一次写入会超出上限时,memory 工具会返回错误,而不是静默丢弃条目。随后 Agent 会自行腾出空间 — 在同一轮中先合并或删除条目,再重试(参见记忆已满时会发生什么)。请注意 replace 同样受此上限约束:用更长的内容替换某个条目仍可能溢出,因此必须缩短新内容(或删除另一个条目)才能容纳得下。
记忆在 System Prompt 中的呈现方式
在每个会话开始时,记忆条目会从磁盘加载并渲染到 system prompt 中,作为一个冻结区块:
══════════════════════════════════════════════
MEMORY (your personal notes) [67% — 1,474/2,200 chars]
══════════════════════════════════════════════
User's project is a Rust web service at ~/code/myapi using Axum + SQLx
§
This machine runs Ubuntu 22.04, has Docker and Podman installed
§
User prefers concise responses, dislikes verbose explanations
该格式包括:
- 显示所属存储区的头部(MEMORY 或 USER PROFILE)
- 使用率百分比和字符计数,以便 Agent 了解剩余容量
- 由
§(分节符)分隔的各个条目 - 条目可以是多行的
**冻结快照模式:**system prompt 的注入内容在会话开始时捕获一次,会话期间永不改变。这是有意为之 — 它保留了 LLM 的前缀缓存以保证性能。当 Agent 在会话过程中添加/删除记忆条目时,变更会立即持久化到磁盘,但要等到下一个会话开始才会出现在 system prompt 中。工具响应始终显示实时状态。
记忆工具的操作
Agent 使用 memory 工具,支持以下操作:
- add — 添加新的记忆条目
- replace — 用更新后的内容替换现有条目(通过
old_text进行子串匹配) - remove — 删除不再相关的条目(通过
old_text进行子串匹配)
没有 read 操作 — 记忆内容会在会话开始时自动注入 system prompt。Agent 将自己的记忆视为对话上下文的一部分。
子串匹配
replace 和 remove 操作使用唯一的短子串匹配 — 你无需提供完整的条目文本。old_text 参数只需要是一个能精确标识唯一条目的子串:
# If memory contains "User prefers dark mode in all editors"
memory(action="replace", target="memory",
old_text="dark mode",
content="User prefers light mode in VS Code, dark mode in terminal")
如果该子串匹配到多个条目,则会返回错误,要求提供更具体的匹配内容。
两种目标详解
memory — Agent 的个人笔记
用于记录 Agent 需要记住的环境、工作流程和经验教训相关的信息:
- 环境信息(操作系统、工具、项目结构)
- 项目约定与配置
- 发现的工具怪癖与变通方法
- 已完成任务的日志条目
- 行之有效的技能与技巧
user — 用户资料
用于记录用户的身份、偏好和沟通风格相关信息:
- 姓名、角色、时区
- 沟通偏好(简洁还是详细、格式偏好)
- 雷区与需要避免的事项
- 工作流程习惯
- 技术水平
该保存什么、该跳过什么
保存这些(主动保存)
Agent 会自动保存 — 你无需开口。当它了解到以下内容时会进行保存:
- 用户偏好:"我更喜欢 TypeScript 而不是 JavaScript" → 保存到
user - 环境信息:"这台服务器运行 Debian 12,搭配 PostgreSQL 16" → 保存到
memory - 纠正:"Docker 命令不要使用
sudo,用户已在 docker 组中" → 保存到memory - 约定:"项目使用 tab 缩进、120 字符行宽、Google 风格 docstring" → 保存到
memory - 已完成的工作:"已于 2026-01-15 将数据库从 MySQL 迁移到 PostgreSQL" → 保存到
memory - 明确的请求:"记住我的 API key 每月轮换一次" → 保存到
memory
跳过这些
- 琐碎/显而易见的信息:"用户询问了 Python" — 太模糊,没有用处
- 容易重新发现的事实:"Python 3.12 支持 f-string 嵌套" — 可以通过网络搜索查到
- **原始数据转储:**大型代码块、日志文件、数据表 — 对记忆来说太大了
- **仅限单次会话的临时内容:**临时文件路径、一次性的调试上下文
- **上下文文件中已有的信息:**SOUL.md 和 AGENTS.md 的内容
容量管理
记忆有严格的字符上限,以保持 system prompt 的规模可控:
| 存储区 | 上限 | 典型条目数 |
|---|---|---|
| memory | 2,200 字符 | 8-15 条 |
| user | 1,375 字符 | 5-10 条 |
记忆已满时会发生什么
当你尝试添加一个会导致超出上限的条目时,工具会返回错误:
{
"success": false,
"error": "Memory at 2,100/2,200 chars. Adding this entry (250 chars) would exceed the limit. Consolidate now: use 'replace' to merge overlapping entries into shorter ones or 'remove' stale or less important entries (see current_entries below), then retry this add — all in this turn.",
"current_entries": ["..."],
"usage": "2,100/2,200"
}
随后 Agent 应当:
- 读取当前条目(错误响应中会显示)
- 找出可以删除或合并的条目
- 使用
replace将相关条目合并成更简短的版本 - 然后
add新条目
**最佳实践:**当记忆使用率超过 80%(可在 system prompt 头部看到)时,应先合并条目,再添加新条目。例如,将三条独立的"项目使用 X"条目合并为一条完整的项目描述条目。
优质记忆条目的实际示例
紧凑、信息密度高的条目效果最好:
# Good: Packs multiple related facts
User runs macOS 14 Sonoma, uses Homebrew, has Docker Desktop and Podman. Shell: zsh with oh-my-zsh. Editor: VS Code with Vim keybindings.
# Good: Specific, actionable convention
Project ~/code/api uses Go 1.22, sqlc for DB queries, chi router. Run tests with 'make test'. CI via GitHub Actions.
# Good: Lesson learned with context
The staging server (10.0.1.50) needs SSH port 2222, not 22. Key is at ~/.ssh/staging_ed25519.
# Bad: Too vague
User has a project.
# Bad: Too verbose
On January 5th, 2026, the user asked me to look at their project which is
located at ~/code/api. I discovered it uses Go version 1.22 and...
重复项防护
内存系统会自动拒绝完全重复的条目。如果你尝试添加已存在的内容,它会返回成功并提示"未添加重复项"。
安全扫描
由于内存条目会被注入到 system prompt 中,因此在接受之前会针对注入和数据外泄模式进行扫描。匹配威胁模式(prompt injection、凭据外泄、SSH 后门)或包含不可见 Unicode 字符的内容将被阻止。
会话搜索
除了 MEMORY.md 和 USER.md 之外,agent 还可以使用 session_search 工具搜索其历史对话:
- 所有 CLI 和消息会话都存储在 SQLite 中(
~/.kopi/state.db),并支持 FTS5 全文搜索 - 搜索查询返回的是数据库中的真实消息 — 无 LLM 摘要、无截断
- agent 可以找到几周前讨论过的内容,即使它们不在其活跃记忆中
- agent 还可以在找到的任何会话中向前/向后滚动
kopi sessions list # Browse past sessions
有关三种调用形式(发现 / 滚动 / 浏览)和响应格式,请参阅会话搜索工具。
session_search 与 memory 的对比
| 特性 | 持久化内存 | 会话搜索 |
|---|---|---|
| 容量 | 总计约 1,300 个 token | 无限制(所有会话) |
| 速度 | 即时(位于 system prompt 中) | FTS5 查询约 20ms,滚动约 1ms |
| 成本 | 每次提示都会消耗 token | 免费 — 不调用 LLM |
| 使用场景 | 随时可用的关键事实 | 查找特定的历史对话 |
| 管理方式 | 由 agent 手动整理 | 自动 — 存储所有会话 |
| Token 成本 | 每个会话固定(约 1,300 个 token) | 按需(需要时才搜索) |
Memory 适用于应始终保留在上下文中的关键事实。会话搜索适用于"我们上周讨论过 X 吗?"这类查询,此时 agent 需要回忆历史对话中的细节。
配置
# In ~/.kopi/config.yaml
memory:
memory_enabled: true
user_profile_enabled: true
memory_char_limit: 2200 # ~800 tokens
user_char_limit: 1375 # ~500 tokens
write_approval: false # false = write freely (default) | true = require approval
控制内存写入(write_approval)
默认情况下,agent 会自由地保存内存 — 包括在一轮对话之后运行的后台自我改进审查中的保存。如果你想先批准保存,请设置 memory.write_approval: true。这是一个简单的开关门控,同时应用于前台轮次和后台审查:
write_approval | 行为 |
|---|---|
false(默认) | 自由写入 — 门控关闭(即门控引入之前的行为)。 |
true | 保存任何内容前都需要批准。在交互式 CLI 中,前台写入会在行内提示你(条目足够小,可以完整阅读)。在其他所有地方 — 消息平台、脚本和后台自我改进审查 — 写入会被暂存(staged),等待你通过 /memory pending 审查。 |
要完全关闭内存(而不只是加以门控),请设置
memory_enabled: false。
从 CLI 或任何消息平台审查暂存的写入:
/memory pending # list staged memory writes (auto ones tagged [auto])
/memory approve <id> # apply one (or 'all')
/memory reject <id> # drop one (or 'all')
/memory approval on # turn the gate on (or 'off') and persist it
这就是"agent 保存了关于我的错误假设"这一问题的解决方案:设置 write_approval: true,这样每一次保存 — 尤其是未经提示的后台保存 — 都会等你给出是/否答复后才会进入你的个人资料。
后台审查通知(display.memory_notifications)
一轮对话结束后,后台自我改进审查可能会悄悄保存一条内存或更新一个 skill。这是 Kopi Agent 的知情同意学习循环:重复的纠正和持久的工作流经验会被转化为紧凑的内存条目或程序性 skill,而 write_approval 可以在这些写入影响未来会话之前将其暂存以供审查。默认情况下,它会在聊天中显示一行简短的 💾 Memory updated,让你知道发生了什么。可以控制其提示的详细程度:
display:
memory_notifications: on # off | on (default) | verbose
| 值 | 行为 |
|---|---|
off | 不显示聊天通知。审查仍会运行并写入 — 你只是看不到对应的提示行。 |
on(默认) | 通用提示行,例如 💾 Memory updated、💾 Skill 'foo' patched。 |
verbose | 包含所变更内容的紧凑预览,例如 💾 Memory ➕ User prefers terse replies 或一段 "old" → "new" skill diff 片段。 |
这只控制网关的聊天通知。审查本身以及对你内存/skill 存储的写入不受此设置影响。可通过
display.platforms.<platform>.memory_notifications按平台进行设置。
使用更便宜的模型运行审查(auxiliary.background_review)
审查默认运行在你的主聊天模型上,会重放对话 — 对话内容已在 prompt cache 中预热,因此属于廉价的缓存读取。如果主模型价格昂贵,你可以改为在更便宜的模型上运行审查:
auxiliary:
background_review:
provider: openrouter
model: google/gemini-3-flash-preview # auto (default) = main chat model
当你将其指向一个与主模型不同的模型时,审查会在该模型上运行,成本大幅降低(基准测试中约降低 3–5 倍)。由于不同的模型本来就无法复用主模型的 prompt cache,该分支会自动重放对话的紧凑摘要(近期轮次逐字保留 + 较早轮次的摘要),而不是完整转录 — 从而最大限度减少写入新缓存的内容。捕获结果保持不变:在测试中,内存捕获与主模型审查完全一致,skill 捕获也几乎一致。
将其保持在 auto(或设置为主模型),一切都不会改变 — 审查继续在主模型上运行,并完整预热缓存重放。
控制 skill 写入(skills.write_approval)
skill 使用相同的开关门控,但审查体验有所不同,因为 SKILL.md 太大了,无法在聊天气泡中阅读:
skills:
write_approval: false # false = write freely (default) | true = require approval
当 write_approval: true 时,skill 写入(create / edit / patch / write_file / delete)无论来源如何都始终暂存。你在行内审查一行摘要,而完整 diff 保留在带外:
/skills pending # list staged skill writes + a one-line gist each
/skills diff <id> # full unified diff (best viewed in CLI or dashboard)
/skills approve <id> # apply it (or 'all')
/skills reject <id> # drop it (or 'all')
/skills approval on # turn the gate on (or 'off') and persist it
在消息平台上,你可以根据摘要 + 元数据批准某个 skill,或者想阅读完整变更时,在 CLI / 仪表板上打开 /skills diff,或查看 ~/.kopi/pending/skills/<id>.json 下的暂存文件。
详细信息请参阅门控 agent skill 写入。
外部 Memory Provider
为了提供超越 MEMORY.md 和 USER.md 的更深入、更持久的记忆能力,Kopi Agent 内置了 8 个外部 memory provider plugin —— 包括 Honcho、OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover 和 Supermemory。
外部 provider 与内置记忆并行运行(绝不替代它),并提供知识图谱、语义搜索、自动事实提取和跨会话用户建模等能力。
kopi memory setup # pick a provider and configure it
kopi memory status # check what's active
有关每个 provider 的完整详情、设置说明和对比,请参阅 Memory Providers 指南。