# AI Memory MCP Server 🧠💾

**让任何 AI 拥有跨会话的持久记忆。**

一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的本地记忆服务器。  
支持 Claude Desktop、OpenCode 及其他所有兼容 MCP 的 AI 客户端。

---

## 解决的问题

每次跟 AI 聊天都要重新自我介绍？聊过的内容下次全不记得？

这不是 AI 的 bug——是大模型的**工作方式决定的**。  
这个项目用最轻量的方式解决了它：**本地 Markdown 文件作为存储，MCP 协议作为桥梁。**

```
第1轮: 聊 → 自动存到本地 md 文件
第2轮: 打开 AI → 自动读取记忆 → AI 认识你
```

---

## 快速开始

### 安装

```bash
# 1. 克隆仓库
git clone https://github.com/chen789654/ai-memory-mcp.git
cd ai-memory-mcp

# 2.（可选）测试是否能启动
python -m src.ai_memory_mcp
# 看到 "AI Memory MCP Server 启动" 即成功
# 按 Ctrl+C 退出
```

### 配置到 Claude Desktop

编辑 `claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "ai-memory": {
      "command": "python",
      "args": ["-m", "src.ai_memory_mcp"],
      "cwd": "你的完整路径/ai-memory-mcp"
    }
  }
}
```

### 配置到 OpenCode

编辑 `opencode.json`：

```json
{
  "mcp": {
    "ai-memory": {
      "type": "local",
      "command": ["python", "-m", "src.ai_memory_mcp"],
      "cwd": "你的完整路径/ai-memory-mcp",
      "enabled": true
    }
  }
}
```

---

## 使用方法

AI 连接后，自动获得以下能力：

### 工具 (Tools)

| 工具 | 作用 | 什么时候用 |
|------|------|-----------|
| `memory_init` | 初始化记忆系统 | 第一次使用 |
| `memory_save` | 保存对话到记忆 | 每次聊完 |
| `memory_load` | 读取所有记忆 | 每次对话开始 |
| `memory_search` | 搜索历史记忆 | 想找之前聊过的内容 |
| `memory_save_person` | 保存人物信息 | 记录用户背景偏好 |
| `memory_status` | 查看系统状态 | 检查运行情况 |

### 给 AI 的指令

在对话开始时，对 AI 说：

> **请执行 memory_load 读取我的记忆**

在对话结束时，对 AI 说：

> **请执行 memory_save 保存今天的对话**

（AI 知道该怎么做——工具定义里已经写清楚了用途。）

---

## 为什么用这个

- **零依赖** — 纯 Python 标准库，不用装任何额外包
- **纯本地** — 数据全在你硬盘上，不经过任何第三方服务器
- **跨平台** — 所有兼容 MCP 的 AI 都能用（Claude/ChatGPT/Gemini 等）
- **可读** — 存储格式是 Markdown，记事本就能打开编辑
- **可搜索** — 全文搜索，比人类记忆靠谱一百倍

---

## 目录结构

```
~/ai-memory/
├── INDEX.md              ← 自动维护的总索引
├── projects/             ← 按项目分文件夹
│   └── 工作助手/
│       ├── _overview.md  ← 项目概览
│       └── 2026-07-14_月度规划.md  ← 每次对话记录
└── people/               ← 人物信息
    └── 用户.md
```

所有文件都是纯文本 Markdown，你可以用任何编辑器直接修改。

---

## License

MIT

---

## 技术概览

| 项目 | 说明 |
|------|------|
| 语言 | Python 3.10+ |
| 协议 | Model Context Protocol (MCP) |
| 架构 | 异步 MCP Server + 本地 Markdown 存储 |
| 依赖 | 零外部依赖（纯 Python 标准库） |
| 兼容 | Claude Desktop / OpenCode / Cursor / Windsurf 等 |
| 存储 | `~/ai-memory/` 下的 Markdown 文件 |

## 功能亮点

- **记忆持久化** — 6 个 MCP 工具覆盖记忆的增删改查
- **项目隔离** — 按项目分别保存对话，互不干扰
- **人物画像** — 跨会话记录用户背景和偏好
- **全文搜索** — 本地 Markdown 全文搜索，秒级响应
- **自动索引** — `INDEX.md` 自动维护，无需手动管理
- **零配置** — 开箱即用，不需要数据库或外部服务

## 截图

> *（使用截图请放在 screenshots/ 目录下）*

---

*Made by chen789654 · 985本硕 · 前互联网大厂 · 现高校教师*