# 🧠 Hermes Memory MCP

**本地增强型记忆系统 + 自我进化能力 · v2.3**

[![e2e](https://img.shields.io/badge/e2e-51%2F51-brightgreen)]() [![MCP Tools](https://img.shields.io/badge/MCP_Tools-31-blue)]() [![Python](https://img.shields.io/badge/Python-3.14-yellow)]() [![License](https://img.shields.io/badge/License-Private-lightgrey)]()

> 基于 Model Context Protocol (MCP) 的本地记忆系统，5 个版本演进到 v2.3 自我进化阶段：从被动存储 → 主动学习 → 智能检索 → 自我进化。

---

## ✨ v2.3 三大自进化能力

| 能力 | 说明 | MCP Tools |
|------|------|-----------|
| **Skill 自动创建** | 从对话上下文抽取 SKILL.md 草稿 → 审核 → 一键部署到 Trae | `auto_create_skill` / `approve_draft_skill` / `list_draft_skills` |
| **周期性 nudge 调度** | 6 个内置后台任务自动维护记忆库（清理/压缩/反思/晋升/健康检查） | `trigger_nudge` / `list_nudges` |
| **Trajectory 训练管道** | 自动捕获所有 MCP Tool 调用 → 导出 JSONL → 用于 RLHF/DPO 微调 | `export_trajectory` / `mark_trajectory_reward` / `get_trajectory_stats` |

## 📊 项目指标

| 维度 | 数据 |
|------|------|
| 端到端测试 | **51 / 51 通过**（v2.1=23 + v2.2=11 + v2.3=17） |
| MCP Tool 总数 | **31**（v2.1=15 + v2.2=7 + v2.3=9） |
| Skill 数 | **5**（memory / evolution / knowledge / reflection / auto-orchestrator） |
| 6 个 nudge | `clean_expired` / `compress_long_session` / `reflect_unreflected` / `cold_memory_warmup` / `cross_project_promote` / `health_check` |
| 数据 Schema | **20 张表**（兼容升级 v2.1 老数据） |

## 🏗️ 架构

```
hermes-mcp/
├── hermes_memory_mcp/        # MCP Server 核心
│   ├── server.py              # 31 个 @mcp.tool() 入口
│   ├── core/                  # MemoryManager（5 版本核心）
│   ├── storage/               # SQLite + ChromaDB
│   ├── orchestrator/          # v2.2 + v2.3 新增
│   │   ├── multisignal.py     # v2.2 多信号融合
│   │   ├── system_prompt.py   # v2.2 三层 Prompt
│   │   ├── pre_compress.py    # v2.2 压缩前捕获
│   │   ├── skill_factory.py   # v2.3 Skill 自动创建
│   │   ├── scheduler.py       # v2.3 nudge 调度
│   │   ├── trajectory.py      # v2.3 Trajectory 训练管道
│   │   └── nudges/            # v2.3 6 个后台任务
│   └── utils/                 # audit / sanitizer / embedder
├── skills/                    # 5 个 Trae Skill
│   └── hermes-{memory,evolution,knowledge,reflection,auto-orchestrator}/
├── tests/                     # e2e + 报告 + 复盘 + 打包
│   ├── test_e2e.py            # v2.1 基础（23 用例）
│   ├── test_v22.py            # v2.2 多信号 + prompt（11 用例）
│   ├── test_v23.py            # v2.3 自进化（17 用例）
│   ├── deployment_report.md   # 部署报告（v2.1 → v2.2 → v2.3）
│   ├── RETROSPECTIVE_v23.md   # v2.3 完整复盘
│   └── build_v23_bundle.py    # 打包脚本
├── .trae/
│   ├── mcp.json               # Trae MCP 配置
│   └── specs/                 # 7 个 spec 文档
│       ├── debug-and-deploy-hermes-mcp/
│       ├── enhance-hermes-memory-mcp/
│       ├── reference-hermes-agent-online/
│       ├── trae-auto-memory/
│       ├── v22-evolution/
│       ├── v23-self-evolution/
│       ├── v23-retrospective-bundle/
│       └── github-publish-v23/
└── hermes_memory_mcp_server.py  # 入口脚本
```

## 🚀 快速开始

```bash
# 1. 安装依赖
pip install mcp chromadb sentence-transformers networkx jieba pyyaml aiofiles

# 2. 配置 Trae MCP（.trae/mcp.json 已就绪）
#    command: C:/Python314/python.exe
#    args: e:/hermes-project/hermes-mcp/hermes_memory_mcp_server.py

# 3. 启动（默认离线 Mock Embedder；设 HERMES_USE_REAL_EMBED=1 用真实模型）
python hermes_memory_mcp_server.py

# 4. 跑端到端测试
python tests/test_e2e.py    # 23/23
python tests/test_v22.py    # 11/11
python tests/test_v23.py    # 17/17

# 5. 打包 v23 交付物
python tests/build_v23_bundle.py
```

## 🧬 5 大版本演进

| 版本 | 阶段 | 关键能力 | 状态 |
|------|------|----------|------|
| v2.0 | 基础 | retain/recall/reflect/evolve | ✅ 17 e2e |
| v2.1 | 自动化 | auto_retain/startup_recall/summarize_session | ✅ 23 e2e |
| v2.2 | 智能化 | 多信号检索 / 三层 prompt / on_pre_compress / Linked / self-healing | ✅ 34 e2e |
| **v2.3** | **自我进化** | **Skill 自动创建 / 6 nudge / Trajectory 训练管道** | **✅ 51 e2e** |

## 📐 业界借鉴

- **NousResearch/hermes-agent** → 三层 System Prompt（v2.2）
- **Letta** → on_pre_compress + 反思代理独立化（v2.2 / v2.3）
- **Mem0** → 多信号融合 + Linked Memory（v2.2）

## 📝 复盘与部署

- 完整复盘：[tests/RETROSPECTIVE_v23.md](tests/RETROSPECTIVE_v23.md)
- 部署报告：[tests/deployment_report.md](tests/deployment_report.md)
- 打包产物：`tests/v23_bundle_*.zip`（48.5KB / 16 文件）

## 📜 License

Private · 仅供 owner=wcy88 内部使用