mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
c3ddf7e322
- Add docs directory with VitePress configuration - Add GitHub Actions workflow for docs build and deploy - Support bilingual (English/Chinese) documentation - Include search, custom theme, and responsive design
10 KiB
10 KiB
Memory 记忆系统
一句话定位
Memory 记忆系统是跨会话知识持久化引擎 — 让 AI 记住项目架构、编码规范和过往决策，新会话自动继承上下文，避免重复解释项目背景。
解决的痛点
| 痛点 | 现状 | Memory 记忆系统方案 |
|---|---|---|
| AI 不理解项目 | 新会话要重新解释项目背景 | Memory 持久化项目上下文 |
| 决策丢失 | AI 的架构决策下次会话就忘了 | Memory 记录架构决策和设计模式 |
| 规范重复 | 每次都要强调编码规范 | CLAUDE.md 自动加载到 Memory |
| 搜索困难 | 找不到之前的讨论内容 | 向量搜索语义相关记忆 |
核心概念速览
| 概念 | 说明 | 命令/位置 |
|---|---|---|
| Core Memory | 核心记忆，存储项目级知识 | ccw core-memory |
| Memory ID | 记忆唯一标识，格式 CMEM-YYYYMMDD-HHMMSS |
自动生成 |
| Memory Cluster | 记忆集群，相关记忆分组 | .cw/memory/clusters/ |
| Embedding | 向量嵌入，支持语义搜索 | core_memory(operation="embed") |
| Stage1 Output | 会话原始输出，用于提取 | Memory V2 管道 |
| Extraction Job | 记忆提取任务，后台异步执行 | ccw core-memory jobs |
使用场景
| 场景 | 说明 | 操作 |
|---|---|---|
| 架构决策 | 记录重要技术决策 | core_memory(operation="import", text="决策内容") |
| 编码规范 | 持久化 CLAUDE.md | 自动导入 |
| 设计模式 | 记录项目使用的设计模式 | 手动添加带标签的记忆 |
| 跨会话上下文 | 新会话加载项目记忆 | 自动加载（通过 hook） |
操作步骤
Memory V2 管道
Memory V2 采用两阶段提取管道：
┌─────────────────────────────────────────────────────────────┐
│ Memory V2 提取管道 │
├─────────────────────────────────────────────────────────────┤
│ │
│ Phase 1: 会话结束后提取 (Rollout Extraction) │
│ ┌─────────────┐ ┌──────────────┐ ┌────────────────┐ │
│ │ 会话结束 │ -> │ 压缩 Transcript│ -> │ Stage1 Output │ │
│ └─────────────┘ └──────────────┘ └────────────────┘ │
│ │ │
│ ▼ │
│ 提取任务调度器 │
│ │ │
│ Phase 2: 后台合并 (Consolidation) │
│ ┌───────────────┐ ┌──────────────┐ ┌─────────────┐│
│ │ 多个 Stage1 │ -> │ LLM 合并提取 │ -> │ Core Memory ││
│ └───────────────┘ └──────────────┘ └─────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘
基础 Memory 操作
# 列出所有记忆
ccw core-memory list
# 列出特定标签的记忆
ccw core-memory list --tags "auth,api"
# 导入新记忆
ccw core-memory import --text "项目使用 JWT 进行身份验证，Token 有效期 24 小时"
# 导出记忆内容
ccw core-memory export --id CMEM-20240215-143000
# 生成 AI 摘要
ccw core-memory summary --id CMEM-20240215-143000 --tool gemini
# 搜索记忆（语义搜索）
ccw core-memory search --query "身份验证" --top-k 5
# 删除记忆
ccw core-memory delete --id CMEM-20240215-143000
Memory 管理
# 查看提取任务状态
ccw core-memory jobs
# 查看特定类型的任务
ccw core-memory jobs --type phase1_extraction
# 按状态筛选
ccw core-memory jobs --status pending
# 手动触发提取
ccw core-memory extract --max-sessions 10
# 手动触发合并
ccw core-memory consolidate
MCP 工具调用
在 Claude Code 中使用 MCP 工具：
// 列出记忆
core_memory(operation="list")
// 带标签筛选
core_memory(operation="list", tags=["auth", "security"])
// 导入记忆
core_memory(operation="import", text="重要内容")
// 导出记忆
core_memory(operation="export", id="CMEM-xxx")
// 生成摘要
core_memory(operation="summary", id="CMEM-xxx", tool="gemini")
// 生成嵌入
core_memory(operation="embed", source_id="CMEM-xxx")
// 语义搜索
core_memory(operation="search", query="authentication", top_k=10, min_score=0.3)
// 检查嵌入状态
core_memory(operation="embed_status")
// 触发提取
core_memory(operation="extract", max_sessions=10)
// 检查提取状态
core_memory(operation="extract_status")
// 触发合并
core_memory(operation="consolidate")
// 检查合并状态
core_memory(operation="consolidate_status")
// 列出任务
core_memory(operation="jobs", kind="extraction", status_filter="pending")
配置说明
Memory V2 配置 (memory-v2-config.ts)
| 配置项 | 默认值 | 说明 |
|---|---|---|
MAX_RAW_MEMORY_CHARS |
300,000 | Stage1 原始记忆最大字符数 |
MAX_SUMMARY_CHARS |
1,200 | 摘要最大字符数 |
MAX_ROLLOUT_BYTES_FOR_PROMPT |
1,000,000 | 发送给 LLM 的最大字节数 |
MAX_RAW_MEMORIES_FOR_GLOBAL |
64 | 合并时包含的原始记忆数量 |
存储路径
.cw/
├── memory/
│ ├── core-memory.db # SQLite 数据库
│ ├── clusters/ # 记忆集群
│ └── embeddings/ # 向量嵌入
Memory 数据结构
interface CoreMemory {
id: string; // CMEM-YYYYMMDD-HHMMSS
content: string; // 记忆内容
summary: string | null; // AI 生成摘要
raw_output?: string; // 原始输出（V2）
created_at: string; // ISO timestamp
updated_at: string; // ISO timestamp
archived: boolean; // 是否归档
metadata?: string; // JSON 元数据
tags?: string[]; // 标签数组
}
Dashboard 中的 Memory 管理
Core Memory 视图
Dashboard 提供 Memory 可视化管理界面：
┌─────────────────────────────────────────────────────────────┐
│ Core Memory 视图 │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 记忆列表 │ │ 记忆详情/编辑 │ │
│ │ - 搜索 │ │ - 内容显示 │ │
│ │ - 标签筛选 │ │ - 标签管理 │ │
│ │ - 排序 │ │ - 摘要生成 │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 提取任务状态 │ │
│ │ - Pending/Running/Done/Error 计数 │ │
│ │ - 任务列表 │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
操作功能
- 浏览记忆: 分页列表，支持搜索和标签筛选
- 编辑记忆: 直接修改内容，自动更新时间戳
- 生成摘要: 一键调用 AI 生成摘要
- 管理标签: 添加/删除标签
- 删除记忆: 软删除（归档）或硬删除
常见问题
Q1: Memory 和 CLAUDE.md 的区别？
A:
- CLAUDE.md: 静态配置文件，手动编写，每次会话完整加载
- Memory: 动态数据库，自动/手动积累，按需搜索和加载
Q2: 如何让 AI 在新会话中自动加载 Memory？
A: 在 settings.json 中配置 hook：
{
"hooks": {
"prePrompt": [
{
"type": "mcp",
"server": "cw-tools",
"tool": "core_memory",
"args": {
"operation": "search",
"query": "{{userPrompt}}",
"top_k": 5
}
}
]
}
}
Q3: Memory V2 管道何时触发？
A: 管道自动触发时机：
- Phase 1: 会话结束时自动提取（如果启用）
- Phase 2: 当 Stage1 outputs 数量达到阈值时自动合并
手动触发：
ccw core-memory extract
ccw core-memory consolidate
Q4: 嵌入搜索需要什么条件？
A: 需要安装 CodexLens Python 环境：
# 检查嵌入状态
ccw core-memory embed-status
# 生成嵌入
ccw core-memory embed --source-id CMEM-xxx
相关功能
- Spec 规范系统 — 规范自动注入
- CLI 调用系统 — ccw core-memory 命令
- CodexLens 代码索引 — 向量嵌入引擎
进阶阅读
- Memory 存储实现:
ccw/src/core/core-memory-store.ts - 提取管道:
ccw/src/core/memory-extraction-pipeline.ts - 任务调度器:
ccw/src/core/memory-job-scheduler.ts - 嵌入桥接:
ccw/src/core/memory-embedder-bridge.ts - MCP 工具:
ccw/src/tools/core-memory.ts