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
290 lines
10 KiB
Markdown
290 lines
10 KiB
Markdown
# 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 操作
|
||
|
||
```bash
|
||
# 列出所有记忆
|
||
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 管理
|
||
|
||
```bash
|
||
# 查看提取任务状态
|
||
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 工具：
|
||
|
||
```typescript
|
||
// 列出记忆
|
||
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 数据结构
|
||
|
||
```typescript
|
||
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：
|
||
|
||
```json
|
||
{
|
||
"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 数量达到阈值时自动合并
|
||
|
||
手动触发：
|
||
```bash
|
||
ccw core-memory extract
|
||
ccw core-memory consolidate
|
||
```
|
||
|
||
### Q4: 嵌入搜索需要什么条件？
|
||
|
||
A: 需要安装 CodexLens Python 环境：
|
||
|
||
```bash
|
||
# 检查嵌入状态
|
||
ccw core-memory embed-status
|
||
|
||
# 生成嵌入
|
||
ccw core-memory embed --source-id CMEM-xxx
|
||
```
|
||
|
||
## 相关功能
|
||
|
||
- [Spec 规范系统](./spec.md) — 规范自动注入
|
||
- [CLI 调用系统](./cli.md) — ccw core-memory 命令
|
||
- [CodexLens 代码索引](./codexlens.md) — 向量嵌入引擎
|
||
|
||
## 进阶阅读
|
||
|
||
- 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`
|