内容
# 代理内存MCP
本地优先，无LLM的AI代理持久内存栈。暴露一个规范的MCP（模型上下文协议）服务器，包含19种工具，涵盖5种内存系统 + 持久任务。
## 亮点
- **五种内存系统，一个MCP服务器**：内存（语义 + FTS5），技能（过程），书签（URL），代码片段（代码），决策（ADR）。任务通过`task_list`单独显示。
- **线性时间保证**：模式验证使用`regex`模块（Thompson NFA）——即使是病态模式也能在O(n)时间内匹配。
- **20毫秒以下的写入**：嵌入缓存 + 内容哈希去重短路昂贵操作；新内容首次保存约3毫秒，重复保存约0.5毫秒。
- **规范响应形状**：每个列表返回 `{items, total, filter}`，每个搜索返回 `{items, total, query, took_ms}`。单一真实来源： [`docs/MCP_API.md`](./docs/MCP_API.md)。
- **模块化**：12个专注的文件（平均约250行）而不是一个庞大的后端。添加新的内存系统是一个自包含的PR。
- **实时捕获模式**：模型可以编写正则表达式捕获短语（`memory_save(category='pattern', ...)`），在30秒内传播到opencode插件，无需重启。
## 架构
```
MCP客户端（opencode代理）
│ stdio JSON-RPC
▼
server.py ─────────► memory.sqlite3
│ 进程内 ├ 内存，技能，书签，代码片段，
│ MLX嵌入 │ 决策，任务，模式
│ （工作线程） ├ core_memory，memory_confidence，embeddings，
│ │ tool_usage，pending
▼
ov_mcp/ ← 模块化包（12个文件）
shapes.py 规范响应助手
core/ 数据库，嵌入，规范化
systems/ 每个内存系统一个文件（原子CRUD）
obs.py 使用情况 + 健康状态
```
单个SQLite文件。数据路径中没有LLM调用。组件之间没有HTTP请求。
## 快速入门
### 要求
- 带有Apple Silicon的macOS（MLX要求）
- Python 3.12+
- `pip install mlx_embeddings regex`
### 安装
```bash
git clone https://github.com/saqlain5544/agent-memory-mcp
cd agent-memory-mcp
pip install mlx_embeddings regex
```
### 作为MCP服务器运行（stdio JSON-RPC）
在 `~/.config/opencode/opencode.json` 中配置：
```json
{
"mcp": {
"agent-memory": {
"type": "local",
"command": [
"/path/to/venv/bin/python",
"/path/to/agent-memory-mcp/server.py"
],
"timeout": 30000
}
}
}
```
### 独立运行（用于测试）
```bash
/path/to/venv/bin/python server.py
# stdio JSON-RPC 已就绪
```
## 工具表面（19种MCP工具）
参见 [`docs/MCP_API.md`](./docs/MCP_API.md) 获取完整的规范参考。工具名称遵循 `<resource>_<verb>`：
| 系统 | 工具 |
|---|---|
| 内存 | `memory_save`，`memory_search`，`memory_recall`，`memory_list`，`memory_delete`，`memory_find_duplicates`，`memory_merge`，`core_memory_get`，`core_memory_set`，`memory_pending`，`memory_approve`，`memory_reject`，`memory_link` |
| 技能 | `skill_create`，`skill_list`，`skill_view`，`skill_search`，`skill_delete` |
| 书签 | `bookmark_save`，`bookmark_list`，`bookmark_search`，`bookmark_delete` |
| 代码片段 | `snippet_save`，`snippet_list`，`snippet_search`，`snippet_delete` |
| 决策 | `decision_log_save`，`decision_log_get`，`decision_log_list`，`decision_log_update`，`decision_log_search` |
| 任务 | `task_create`，`task_list`，`task_get`，`task_update`，`task_complete`，`task_delete` |
| 可观察性 | `memory_health`，`memory_usage_stats` |
## 何时使用哪种内存系统
| 您学到了什么 | 系统 | 类别 |
|---|---|---|
| 关于某事工作原理的见解 | 内存 | `insight` |
| 未文档化的经验教训 | 内存 | `gotcha` |
| 用户纠正的方法 | 内存 | `correction` |
| recurring 工具错误 | 内存 | `error` |
| 值得保留的设计决策 | 决策 | （ADR 形状） |
| 可重用的代码块 | 代码片段 | （语言标记） |
| 值得保留的外部文档/URL | 书签 | （URL） |
| 生存会话的待办事项 | 任务 | （优先级 + due_at） |
| 多步骤过程 | 技能 | （带有触发器） |
## 性能
| 路径 | 目标 p50 |
|---|---|
| `memory_save`（新） | <5毫秒 |
| `memory_save`（重复命中） | <0.5毫秒 |
| `memory_save`（重复） | <0.5毫秒 |
| `memory_search` | <1毫秒 |
| `memory_recall` | <1毫秒 |
| `bookmark_*`，`snippet_*` 等 | <0.5毫秒 |
| `memory_health` | <1毫秒 |
## 许可证
MIT
