# ebbingflow-mcp

**EbbingFlow 长期记忆的 MCP 集成桥** —— 一个轻量 stdio MCP Server，把 [EbbingFlow](https://github.com/MMX920/ebbingflow) 的记忆能力以 MCP 工具形式接入 OpenCode / Claude / 任意 MCP 客户端。

## 这是什么

针对"对话一长 AI 就丢失前文"的上下文记忆痛点：EbbingFlow 是本地部署的开源 AI 记忆引擎（Neo4j 知识图谱 + 向量 + SQL 证据链 + Ebbinghaus 遗忘曲线）。本仓库提供一个**薄桥接层**，将记忆能力封装为 4 个 MCP 工具，让 Agent 能跨会话写入、检索、溯源记忆。

```
┌────────────┐   stdio(MCP)   ┌────────────────┐   HTTP    ┌──────────────┐
│ OpenCode / │ ◄────────────► │  ebbingflow-mcp │ ◄───────► │  EbbingFlow  │
│ 任意 MCP    │   4 个工具      │  (本仓库)        │          │  核心服务      │
│ 客户端      │                │  薄转发，无状态   │          │ localhost:8000│
└────────────┘                └────────────────┘          └──────────────┘
```

设计要点：本桥**不直接触碰** Chroma/Neo4j/SQLite，只把请求转发给已运行的 EbbingFlow HTTP 服务（默认 `localhost:8000`），避免多进程对本地持久化存储的锁冲突。

## 提供的工具

| 工具 | 说明 |
|------|------|
| `remember` | 写入一条长期记忆（经 EbbingFlow 抽取事实 → 图谱 + 向量 + 证据链） |
| `recall` | 多轨检索（图谱/向量/BM25/SQL/剧情），按 Ebbinghaus 衰减排序 |
| `chat` | 带完整记忆上下文的对话（回复也会回写记忆） |
| `health` | 检查 EbbingFlow 核心服务是否在线 |

## 前置要求

1. EbbingFlow 核心服务已启动并监听 `localhost:8000`（上游仓库：https://github.com/MMX920/ebbingflow）
2. Python 3.10+

```bash
pip install -r requirements.txt
```

## 运行与配置

环境变量（均可选，有默认值）：

| 变量 | 默认 | 说明 |
|------|------|------|
| `EBBINGFLOW_BASE_URL` | `http://localhost:8000` | EbbingFlow 核心服务地址 |
| `EBBINGFLOW_USER_ID` | `user_001` | 记忆归属的用户 ID |
| `EBBINGFLOW_MCP_NAME` | `ebbingflow` | MCP Server 名称 |
| `EBBINGFLOW_MCP_TIMEOUT` | `120` | 请求上游的超时秒数 |

直接运行：

```bash
python mcp_server.py
```

接入 OpenCode（`opencode.jsonc`）：

```jsonc
{
  "mcp": {
    "ebbingflow": {
      "type": "local",
      "command": ["python", "/path/to/ebbingflow-mcp/mcp_server.py"],
      "enabled": true
    }
  }
}
```

## 示例

```text
# 写入
remember: "用户正在求职 AI 应用方向岗位"
→ remembered. engine confirmation: 已记住...

# 检索
recall: "用户求职什么方向"
→ 1. [GRAPH] ... [score=0.9, source=关系网]
```

## 许可

- 本仓库（MCP 集成桥）：**MIT**
- 上游 EbbingFlow 引擎：Apache-2.0（见 [MMX920/ebbingflow](https://github.com/MMX920/ebbingflow)）