Programming Agent Self-Learning Memory Engine

An MCP (Model Context Protocol)-based self-learning memory engine that provides programming agents with a four-layer closed-loop learning capability: "Perceive-Reflect-Consolidate-Apply". It lets agents learn from mistakes and get better with use.

Architecture Overview

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

Related MCP server: recall-memory-mcp

Four-Layer Closed Loop

Installation

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

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

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

Configuring the MCP Server

ZCode / Claude Code

Add the following to the MCP configuration file:

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

Replace <absolute path to the project root> with the actual path where this project is cloned/stored on your machine (i.e., the directory containing pyproject.toml), for example D:/tools/memory-engine on Windows, or /home/user/tools/memory-engine on macOS/Linux.

Cursor / VS Code

Add the same configuration in .cursor/mcp.json or the MCP settings in VS Code.

Standalone Run (for debugging)

cd memory-engine
python -m memory_engine.server

Core Workflow

0. Capturing Conversation Signals (Perception Enhancement)

During vibe coding, operators often leave explicit signals in the conversation—emphatic instructions such as "please note" or "please remember"—as well as complaints caused by the agent repeatedly making the same mistakes ("why again...", "how many times have I told you..."). These statements are the highest-value learning material and should be captured and incorporated into memory:

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

The detector identifies four types of signals and ranks them by priority:

Detection results are automatically recorded as conversation_signal type observations. During reflection, a specially tailored prompt is used (inferring past mistakes + distilling into imperative rules), and the subsequent flow is identical to error reflection.

1. Recording Errors (Perception)

When a tool execution fails, the agent calls:

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

2. Reflection Analysis (Reflection)

Get the analysis prompt:

get_reflection_prompt(obs_id="abc123")

The agent analyzes the root cause based on the returned prompt, then saves the result:

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. Distilling Skills (Consolidation)

After accumulating enough experience, check whether a skill can be distilled:

check_consolidation()

Create the skill:

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. Retrieval and Application (Application)

Before starting a new task, retrieve relevant experience:

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

Returns context containing relevant skills and cases, injected directly into the prompt.

Memory Hierarchy

Data Storage

• SQLite database (data/memories.db): structured storage, supports FTS5 full-text search

• JSONL log (data/observations.jsonl): append-only log of raw observation records

• Markdown files (data/skills/): generated skill documents, human-readable and version-controllable

Project Structure

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       # 测试

Error Categories

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

Design Philosophy

• No external LLM dependency: reflection and skill distillation are done by the caller (the agent itself); the engine only provides the framework and storage

• MCP-native: runs as a standard MCP server; any MCP-capable agent can connect directly

• Human-machine collaboration: all memories and skills are stored in human-readable formats (Markdown, JSON) for easy review and maintenance

• Progressive learning: from single errors → episodic memory → semantic memory → skills, abstracting layer by layer and refining gradually