cli-agent-orchestrator 记忆系统深度解析:5 种作用域让 AI 跨会话记住你的项目

原创2026-10-11 17:54:511,996 阅读

cli-agent-orchestrator 记忆系统深度解析:5 种作用域让 AI 跨会话记住你的项目

cli-agent-orchestrator 是一款面向 Claude Code、Kiro、Codex 等 AI 编码 CLI 的多智能体编排工具,它的**记忆系统(Memory System)**能让 Agent 把事实、决策和偏好持久化下来,并在下一次会话启动时自动注入回上下文——真正做到跨会话记住你的项目。本文带你轻松看懂它的 5 种作用域(global、project、session、agent、federated)、底层双存储架构,以及日常常用的管理命令。

cli-agent-orchestrator 记忆系统所在的多智能体编排架构:Supervisor Agent 协调多个 Worker Agent

为什么 AI 编码工具需要一个记忆系统?

没有记忆时,每次新开一个会话,Agent 都像是"第一次见到你的项目":你昨天告诉它"本项目只用 pytest",今天它又开始推荐 unittest。

cli-agent-orchestrator 的记忆系统解决的就是这个问题:

  • 🧠 Agent 在会话中随时存储事实、决策和偏好
  • 📥 新会话启动时自动注入相关记忆,Agent 无需再问一遍
  • 🔎 Agent 可以用关键词主动召回记忆,也可以遗忘过时内容
  • 🏥 内置 lint、compact、heal 等维护命令,让记忆"库"保持健康

完整说明见官方文档 docs/memory.md。

一分钟理解记忆的工作流程

整个链路只有 4 步:

  1. 存储:Agent 在会话中调用 memory_store MCP 工具写入一条记忆
  2. 持久化:CAO 把它写成 Markdown wiki 文件,并同步到 SQLite 元数据索引
  3. 注入:下次会话启动时,CAO 把匹配的记忆以 <cao-memory> 块形式前置到 Agent 的第一条消息里
  4. 召回: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:属于"角色"的专属知识

cli-agent-orchestrator 记忆系统中 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:

  1. 首条消息前置块:会话首条消息前加一个 <cao-memory> 块,列出按作用域优先级(session > project > global)挑选的记忆
  2. 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 记住你的项目

  1. 正常启动 Agent:记忆随 cao-mcp-server 内置提供,无需额外安装
  2. 给 Agent profile 加一段 ## Memory 指引:告诉它"发现值得记住的偏好、约定、决策时用 memory_store 立即存下,存结论不存对话"
  3. 用 cao memory list 验证:确认记忆按预期落到了正确的作用域
  4. 定期体检: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 后端扩展)。

登录后查看全文
cli-agent-orchestrator