cli-agent-orchestrator 记忆系统深度解析:5 种作用域让 AI 跨会话记住你的项目
cli-agent-orchestrator 记忆系统深度解析:5 种作用域让 AI 跨会话记住你的项目
cli-agent-orchestrator 是一款面向 Claude Code、Kiro、Codex 等 AI 编码 CLI 的多智能体编排工具,它的**记忆系统(Memory System)**能让 Agent 把事实、决策和偏好持久化下来,并在下一次会话启动时自动注入回上下文——真正做到跨会话记住你的项目。本文带你轻松看懂它的 5 种作用域(global、project、session、agent、federated)、底层双存储架构,以及日常常用的管理命令。
为什么 AI 编码工具需要一个记忆系统?
没有记忆时,每次新开一个会话,Agent 都像是"第一次见到你的项目":你昨天告诉它"本项目只用 pytest",今天它又开始推荐 unittest。
cli-agent-orchestrator 的记忆系统解决的就是这个问题:
- 🧠 Agent 在会话中随时存储事实、决策和偏好
- 📥 新会话启动时自动注入相关记忆,Agent 无需再问一遍
- 🔎 Agent 可以用关键词主动召回记忆,也可以遗忘过时内容
- 🏥 内置 lint、compact、heal 等维护命令,让记忆"库"保持健康
完整说明见官方文档 docs/memory.md。
一分钟理解记忆的工作流程
整个链路只有 4 步:
- 存储:Agent 在会话中调用
memory_storeMCP 工具写入一条记忆 - 持久化:CAO 把它写成 Markdown wiki 文件,并同步到 SQLite 元数据索引
- 注入:下次会话启动时,CAO 把匹配的记忆以
<cao-memory>块形式前置到 Agent 的第一条消息里 - 召回:Agent 需要时随时用
memory_recall主动搜索
也就是说,记忆的写入只走 MCP 通道,读取和日常维护(列表、查看、清理、体检)则可以直接用 cao memory CLI 完成。
5 种记忆作用域全解
作用域(scope)决定记忆存在哪、谁能读到,是这套系统最重要的概念。一张表看懂:
| 作用域 | 存储位置 | 典型用途 | 保留期 |
|---|---|---|---|
global |
memory/global/wiki/global/ |
跨项目事实:用户偏好、编码规范 | 永不过期 |
project(默认) |
memory/{project_id}/wiki/project/ |
项目专属:架构决策、项目约定 | 最后更新后 90 天 |
session |
memory/global/wiki/session/{session_name}/ |
临时笔记,仅当前会话有效 | 14 天 |
agent |
memory/global/wiki/agent/{agent_profile}/ |
角色专属:某角色始终遵循的模式 | 永不过期 |
federated |
memory/federated/wiki/federated/ |
本机共享层:整台机器所有项目共享的事实 | 永不过期 |
global:你的"个人习惯"仓库
存用户偏好和编码风格,例如"回答要简洁,不要结尾总结"。global 不需要任何 ID,跨项目生效,且永不过期。
project:默认作用域,项目的"长期记忆"
存架构决策、技术选型、项目约定。project 是默认作用域,CAO 会按优先级解析项目身份:CAO_PROJECT_ID 环境变量 → 归一化后的 git remote URL → 工作目录路径的 sha256 前 12 位。这意味着你重命名或移动目录后,项目记忆依然能被正确召回。
session:只服务当前会话的临时便签
适合"本次会话复用现有 auth 中间件,不要重写"这类临时决定。会话结束 14 天后自动清理,不会污染长期记忆。
agent:属于"角色"的专属知识
如果你的团队配置了 developer、reviewer 等多个角色,agent 作用域可以为每个角色单独沉淀经验。比如 reviewer 角色始终"先检查错误处理是否缺失"。同一个 key(如 review-notes)在不同角色下会落在不同文件,互不干扰。
federated:整台机器的共享知识层
适合"本机内部 PyPI 源地址"这类与具体项目无关、但全机通用的事实,供本机上所有项目的 Agent 共享。
scope 与 type:最容易搞混的一对概念
scope决定记忆存在哪里(位置唯一由它控制)memory_type只是一个分类标签,不影响存储位置
| 类型 | 用途 |
|---|---|
project(默认) |
架构笔记、项目约定 |
user |
用户偏好、工作风格 |
feedback |
纠正记录、要规避的重复错误 |
reference |
外部资源、文档指针 |
💡 注意:并没有 "user 作用域"。所谓"用户记忆"只是 memory_type="user" 的标签,按惯例存在 scope="global" 下。另外,user 和 feedback 类型被视为"人工策展知识",任何情况下都不会过期。
底层双存储架构:Markdown + SQLite
记忆系统由两个联动的存储组成(核心实现在 memory_service.py):
| 存储 | 角色 | 说明 |
|---|---|---|
| Markdown wiki 文件 | 内容存储 | 每条记忆一个文件,人类可读,带时间戳条目 |
SQLite memory_metadata 表 |
元数据索引 | 每个 wiki 文件对应一行,记录标签、访问时间戳、使用次数等 |
每次 memory_store 写入会同时更新 Markdown 文件和 SQLite 行;每次 memory_recall 检索时,BM25 关键词搜索跑在 wiki 内容上,而新鲜度、使用频率和综合评分(BM25 + 新鲜度 + 使用量三因子)读取 SQLite 元数据列,两者结合出排序结果。
MCP 工具(memory_store、memory_recall、memory_forget)定义在 mcp_server/server.py。
记忆如何自动注入到新会话?
CAO 通过两条通道把相关记忆"塞回"给 Agent:
- 首条消息前置块:会话首条消息前加一个
<cao-memory>块,列出按作用域优先级(session>project>global)挑选的记忆 - Provider 配置文件:对 Claude Code、Codex、Kiro CLI,CAO 会在创建终端时把同样的块写入各家的项目配置文件(如
.claude/CLAUDE.md),并用标记分隔,重复运行只会覆盖同一区段
为避免某个作用域"刷屏",注入有硬预算:每个作用域最多 10 条、最多 1000 字符(见 constants.py 中的 MEMORY_MAX_PER_SCOPE 与 MEMORY_SCOPE_BUDGET_CHARS)。
常用管理命令速查
所有维护命令都在 cao memory 下(源码见 cli/commands/memory.py):
| 命令 | 用途 |
|---|---|
cao memory list --all |
查看全部项目的记忆 |
cao memory show <key> |
查看某条记忆全文 |
cao memory delete <key> |
删除单条记忆 |
cao memory lint |
体检:孤儿页、矛盾、过期断言等 |
cao memory compact |
用 LLM 编译器压缩整理某个主题 |
cao memory heal --apply |
把 lint 问题自动修复(默认 dry-run) |
cao memory export / import |
导出/导入记忆包(OKF 归档),支持 --redact 脱敏 |
4 步上手:让 Agent 记住你的项目
- 正常启动 Agent:记忆随
cao-mcp-server内置提供,无需额外安装 - 给 Agent profile 加一段
## Memory指引:告诉它"发现值得记住的偏好、约定、决策时用memory_store立即存下,存结论不存对话" - 用
cao memory list验证:确认记忆按预期落到了正确的作用域 - 定期体检:
cao memory lint+cao memory heal保持记忆库干净;过期内容会按保留期策略自动清理
写在最后
cli-agent-orchestrator 的记忆系统用"5 种作用域 + 4 种类型"的正交设计,把"存在哪"和"是什么"彻底解耦,再用 Markdown 可读写 + SQLite 可检索的组合兼顾了透明度与性能。无论是个人偏好、项目约定还是角色经验,AI 都能跨会话、跨项目地记住——这正是多智能体长期协作的基础设施。
延伸阅读:docs/memory.md(记忆系统全文)、docs/self-learning.md(基于记忆的自学习闭环)、docs/obsidian-vault.md(Vault 后端扩展)。

