记忆系统

目录结构

agents/
└── {agent_id}/
    └── memory/
        ├── MEMORY.md                  # 长期记忆（Agent 经验 + 模式）
        ├── history.jsonl              # 内部任务记录（工具调用、自省）
        ├── .dream_cursor              # 全局 Dream 进度
        ├── .git/                      # Git 版本仓库
        ├── users/                     # 按用户隔离（NEW）
        │   └── {user_hash}/
        │       ├── PROFILE.md         # 用户偏好、习惯、重要事实
        │       ├── history.jsonl      # 对话历史
        │       └── .dream_cursor      # 每个用户的 Dream 进度
        └── daily/                     # 每日日志（可选）
            └── YYYY-MM-DD.md

MEMORY.md

长期记忆文件，由 Dream 过程维护，在 system prompt 的 ## Your Long-Term Memory 节注入。

存储内容：

• Agent 自身学到的工作模式和操作习惯
• 任务执行中发现的系统信息和决策记录
• 不存储团队知识（走 wiki）和用户画像（走 PROFILE.md）

代码架构 (MemoryStore)

定义于 cococat/memory/store.py，由 5 个独立子模块组合（非多继承）：

子模块	文件	职责
ManualMemory	manual.py	remember / recall / forget / load_for_system_prompt
DreamMemory	dream.py	自动从对话会话提取事实
SummarizeMemory	summarize.py	即时会话摘要（Ticker）
CompileMemory	compile.py	周期摘要编译（today → week → longterm）
FactsMemory	facts.py	FTS5 原子事实提取和索引

每个子模块在构造函数中显式声明依赖（memory_dir, db, get_llm），可独立测试。

Dream 过程

Dream 过程

定义于 cococat/memory/dream.py（DreamMemory.dream()）。由 session.py:maybe_trigger_dream() 触发。

触发条件：对话历史行数 ≥ 50 行时，fire-and-forget 异步启动。

流程：

1. 读取 session.jsonl
2. 读取现有 memory.md
3. LLM 分析提取关键事实（决策、偏好、项目信息）
4. 新增事实追加到 memory.md（自动去重）
5. 截断会话文件保留最近 30 行

Per-User Dream

每个对话用户有独立的 PROFILE.md 和 Dream 进度：

• run_user_dream() 独立处理每个用户的对话历史
• 用户哈希：sha256(user_id)[:16]，避免特殊字符
• 系统提示注入 ## Current User\n{PROFILE.md}

GitStore 版本控制

定义于 cococat/core/git_store.py：

• 每次 Dream 写入后自动 git add + git commit
• 支持 revert_memory 工具回滚最近一次 commit
• Web API：GET /api/agents/{id}/memory/history 查看 git log
• 每个 agent memory 目录独立 git 仓库

历史压缩 (AutoCompact)

定义于 cococat/core/auto_compact.py，在心跳空闲时触发：

• 扫描 users/{hash}/history.jsonl 检查是否超过字符预算（默认 32K）
• 超过 → 旧条目压缩为摘要（{"type": "compacted_summary", ...}）
• 保留最近 5 条完整条目
• 压缩失败不影响后续（外层 try/except 保护）

Consolidator（运行时压缩）

定义于 cococat/core/agent.py，在 ReAct 循环中实时生效：

• Token 预算：8000 tokens
• 按完整轮次边界切分（不切断 tool_call → tool_result 配对）
• LLM 摘要 + 递归多轮压缩
• _snip_history 作为硬截断兜底（保留最后 4 条非系统消息）

数据流

会话消息 → Consolidator（实时 token 预算）
     ↓
history.jsonl（追加写入，游标格式）
     ↓
Dream（按计划触发）
     ↓
MEMORY.md（手术式编辑）
     ↓
GitStore（自动版本化）