# 编程智能体自我学习记忆引擎

一个基于 MCP（Model Context Protocol）的自我学习记忆引擎，为编程智能体提供 **"感知-反思-沉淀-应用"** 四层闭环学习能力。让智能体从错误中学习，越用越强。

## 架构概览

```
┌──────────────────────────────────────────────────────┐
│                    编程智能体                          │
│  (Claude Code / Cursor / 任何支持 MCP 的智能体)       │
└──────────┬───────────────────────┬────────────────────┘
           │ MCP Protocol          │
    ┌──────▼──────┐         ┌──────▼──────┐
    │  应用层      │         │  感知层      │
    │  检索+注入   │         │  错误捕获    │
    └──────┬──────┘         └──────┬──────┘
           │                       │
    ┌──────▼──────┐         ┌──────▼──────┐
    │  沉淀层      │         │  反思层      │
    │  技能+记忆   │◄────────│  根因分析    │
    └──────┬──────┘         └─────────────┘
           │
    ┌──────▼──────┐
    │  存储层      │
    │  SQLite+FTS5 │
    └─────────────┘
```

## 四层闭环

| 层 | 职责 | MCP 工具 |
|---|---|---|
| **感知层** Observation | 捕获工具执行错误、测试失败、用户纠正、对话信号 | `record_observation`, `capture_conversation_signals`, `get_pending_observations` |
| **反思层** Reflection | 根因分析，提取可复用经验 | `get_reflection_prompt`, `reflect_and_save`, `batch_get_reflection_prompts` |
| **沉淀层** Consolidation | 提炼技能，生成 SKILL.md，维护记忆 | `create_skill`, `get_skill_prompt`, `list_skills`, `get_skill`, `check_consolidation` |
| **应用层** Application | 检索相关经验，注入任务上下文 | `get_context`, `search_memory`, `search_skill` |
| **统计** | 查看引擎状态 | `get_stats` |

## 安装

```bash
# 进入项目目录（替换为你本机的实际路径）
cd memory-engine

# 安装依赖（绕过代理）
pip install --no-proxy -e .

# 或手动安装
pip install --no-proxy mcp[cli] jieba
```

## 配置 MCP 服务器

### ZCode / Claude Code

在 MCP 配置文件中添加：

```json
{
  "mcpServers": {
    "memory-engine": {
      "command": "python",
      "args": ["-m", "memory_engine.server"],
      "cwd": "<项目根目录的绝对路径>"
    }
  }
}
```

> 将 `<项目根目录的绝对路径>` 替换为本机克隆/存放本项目的实际路径（即包含 `pyproject.toml` 的目录），例如 Windows 上形如 `D:/tools/memory-engine`，macOS/Linux 上形如 `/home/user/tools/memory-engine`。

### Cursor / VS Code

在 `.cursor/mcp.json` 或 VS Code 的 MCP 设置中添加同样的配置。

### 独立运行（调试用）

```bash
cd memory-engine
python -m memory_engine.server
```

## 核心工作流

### 0. 捕获对话信号（感知增强）

vibe coding 过程中，操作者常在对话里留下显式信号——"请注意"、"请记住"等强调指令，
以及因智能体重复犯错产生的埋怨（"怎么又……"、"我说过多少次了……"）。
这些语句是最高价值的学习素材，应捕获并纳入记忆：

```
capture_conversation_signals(
  conversation_text="用户: 请注意，bat文件必须用ANSI编码
用户: 怎么又是编码问题，我说过多少次了",
  auto_record=true
)
```

检测器识别四类信号并按优先级排序：

| 信号 | 识别示例 | 含义 |
|---|---|---|
| `complaint` | "怎么又"、"还是不对"、"我说过多少次" | 重复犯错引发的埋怨，说明此前教训未被吸取（最高优先级） |
| `emphasis` | "请注意"、"请记住"、"务必"、"千万别" | 用户显式强调的规则 |
| `preference` | "以后都用"、"我喜欢"、"请默认" | 用户对工作方式的偏好 |
| `frustration` | "无语"、"太慢了"、"浪费时间" | 不满情绪，提示效率/体验问题 |

检测结果自动记录为 `conversation_signal` 类型观察，反思时使用专门定制的提示词
（推断既往错误 + 提炼为祈使句规则），后续流程与错误反思一致。

### 1. 记录错误（感知）

当工具执行失败时，智能体调用：

```
record_observation(
  obs_type="tool_error",
  tool_name="Bash",
  error_message="bat文件执行报错：编码错误",
  context="在Windows上创建的bat文件包含中文注释",
  tags="encoding,windows,bat"
)
```

### 2. 反思分析（反思）

获取分析提示词：

```
get_reflection_prompt(obs_id="abc123")
```

智能体根据返回的提示词分析根因，然后保存结果：

```
reflect_and_save(
  obs_id="abc123",
  root_cause="Windows的cmd.exe默认使用系统ANSI编码，UTF-8编码的bat文件会导致中文注释被解析错误",
  category="encoding",
  lesson="在Windows上创建bat文件时，文件必须使用ANSI/GBK编码，而非UTF-8",
  solution="将bat文件保存为ANSI编码，或使用chcp 65001切换代码页",
  tags="encoding,windows,bat,cmd",
  generalizable=true
)
```

### 3. 提炼技能（沉淀）

积累足够经验后，检查是否可以提炼技能：

```
check_consolidation()
```

创建技能：

```
create_skill(
  name="windows-bat-encoding",
  description="Windows bat文件中文编码问题的处理方法",
  trigger_conditions="创建或编辑.bat文件\n在Windows上运行脚本失败且涉及中文",
  steps="将文件保存为ANSI编码\n或使用chcp 65001 + UTF-8 BOM",
  caveats="chcp 65001仅在当前cmd会话有效\n某些旧版Windows不支持UTF-8 BOM",
  category="encoding"
)
```

### 4. 检索应用（应用）

开始新任务前，获取相关经验：

```
get_context(task_description="需要创建一个Windows批处理脚本来部署应用")
```

返回包含相关技能和案例的上下文，直接注入到 prompt 中。

## 记忆分层

| 类型 | 说明 | 示例 |
|---|---|---|
| **情景记忆** Episodic | 具体的"故事"，某次修复的完整记录 | "2024-01-15 修复了XX项目的bat编码问题" |
| **语义记忆** Semantic | 抽象化的规则和教训 | "Windows上bat文件应使用ANSI编码" |
| **技能** Skill | 标准化的可执行操作指南 | SKILL.md 文件 |

## 数据存储

- **SQLite 数据库** (`data/memories.db`)：结构化存储，支持 FTS5 全文检索
- **JSONL 日志** (`data/observations.jsonl`)：原始观察记录的追加日志
- **Markdown 文件** (`data/skills/`)：生成的技能文档，人类可读，可版本控制

## 项目结构

```
memory-engine/
├── 开发思路.md              # 设计文档
├── README.md                # 本文件
├── pyproject.toml           # Python 项目配置
├── requirements.txt         # 依赖列表
├── config/
│   └── settings.json        # 引擎配置
├── src/memory_engine/
│   ├── __init__.py
│   ├── server.py            # MCP 服务器入口（15个工具）
│   ├── models/
│   │   └── schemas.py       # 数据模型
│   ├── observation/
│   │   ├── collector.py     # 感知层：错误收集器
│   │   └── signal_detector.py # 感知层：对话信号检测器
│   ├── reflection/
│   │   └── analyzer.py      # 反思层：根因分析器
│   ├── consolidation/
│   │   ├── memory_store.py  # 存储层：SQLite + FTS5
│   │   └── skill_generator.py # 沉淀层：技能生成器
│   └── application/
│       └── retriever.py     # 应用层：记忆检索器
├── data/
│   ├── memories.db          # SQLite 数据库（运行后生成）
│   ├── observations.jsonl   # 观察日志（运行后生成）
│   └── skills/              # 技能 Markdown（运行后生成）
└── tests/
    └── test_engine.py       # 测试
```

## 错误类别

`encoding` | `build_error` | `runtime_error` | `test_failure` | `dependency` | `configuration` | `platform_specific` | `performance` | `security` | `best_practice` | `api_usage` | `preference` | `communication` | `other`

## 设计理念

- **不依赖外部 LLM**：反思和技能提炼由调用方（智能体本身）完成，引擎只提供框架和存储
- **MCP 原生**：作为标准 MCP 服务器运行，任何支持 MCP 的智能体都可以直接接入
- **人机协同**：所有记忆和技能都以人类可读的格式存储（Markdown、JSON），便于审查和维护
- **渐进式学习**：从单次错误→情景记忆→语义记忆→技能，层层抽象，逐步提炼