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

一个基于 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

安装

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

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

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

配置 MCP 服务器

ZCode / Claude Code

在 MCP 配置文件中添加：

{
  "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 设置中添加同样的配置。

独立运行（调试用）

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），便于审查和维护
• 渐进式学习：从单次错误→情景记忆→语义记忆→技能，层层抽象，逐步提炼