# ima-memory-mcp

基于 IMA 笔记 + IMA 知识库的 AI Agent 持久化记忆与跨会话共享 MCP Server。

- 以 IMA 笔记存储记忆与会话存档
- 每篇笔记创建后自动关联到 IMA 知识库，实现跨工具共享
- 纯 MCP 设计，无插件，支持 Kimi Code、OpenCode、Cursor 等任何 MCP 客户端

## 前置条件

- Node.js 18+
- 一个 IMA OpenAPI 账号及凭证（Client ID + API Key）
- 在 IMA 客户端中创建一个知识库，用于存放共享记忆

## 安装

```bash
# 1. 从 GitHub 克隆到任意目录
git clone https://github.com/mason-yb-zhang/ima-memory-mcp.git
cd ima-memory-mcp

# 2. 安装依赖
npm install

# 3. 配置 IMA 凭证
mkdir -p ~/.config/ima
echo "your-client-id" > ~/.config/ima/client_id
echo "your-api-key" > ~/.config/ima/api_key

# 4. （可选）指定默认知识库名称或 ID
# 默认会查找名为 Agent-Memory-KB 的知识库；也可直接指定 ID：
echo "your-kb-id" > ~/.config/ima/memory_kb_id

# 5. 注册 MCP server
node scripts/install.mjs
```

然后**重启 Kimi Code CLI**（或你使用的其他 MCP 客户端）。

### 凭证获取

访问 https://ima.qq.com/agent-interface 申请 IMA OpenAPI 的 Client ID 和 API Key。

## 工具列表

### 记忆管理

- `add_memory` — 保存记忆
- `search_memory` — 搜索记忆
- `list_memories` — 列出记忆
- `update_memory` — 追加更新
- `delete_memory` — 标记删除
- `decay_memories` — 清理冷短期记忆
- `promote_memory` — 升级为长期记忆

### 会话存档

- `save_session` — 存档会话
- `list_sessions` — 列出存档
- `search_session` — 搜索会话
- `get_session_detail` — 读取会话全文

## 使用示例

```text
记住：我喜欢用 TypeScript，不要在代码里写冗余注释。

搜索之前关于数据库选型的记忆。

保存当前会话，标题叫"Docker 部署讨论"。
```

## 存储结构

- 记忆笔记：IMA 笔记本 `Agent-Memories`
- 会话存档：IMA 笔记本 `Agent-Sessions`
- 知识库同步：每篇笔记创建后自动通过 `add_knowledge(media_type=11)` 关联到 IMA 知识库
  - 默认知识库名称：`Agent-Memory-KB`
  - 可通过环境变量 `IMA_MEMORY_KB_NAME` 修改名称
  - 可通过环境变量 `IMA_MEMORY_KB_ID` 或文件 `~/.config/ima/memory_kb_id` 直接指定知识库 ID
- 每条记忆 / 每个会话既是一篇 IMA 笔记，也是知识库中的一个条目

## 跨工具共享

所有接入同一个 `ima-memory` MCP Server 的 AI 工具（Kimi Code、OpenCode、Cursor 等）读写同一份 IMA 凭证和同一个知识库，因此天然共享同一个记忆空间。

## 注意事项

由于 IMA OpenAPI 的限制：

1. 不支持真正删除笔记，`delete_memory` 仅追加 `[DELETED]` 标记。
2. 不支持替换笔记正文，`update_memory` 仅追加 `[UPDATED]` 标记。
3. 标题一旦创建无法修改，因此 `promote_memory` 也只能追加标记。

## License

MIT