内容
# 智能记忆MCP服务端
[](https://github.com/agorokh/agentic-memory-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](pyproject.toml)
[](https://modelcontextprotocol.io/)
**一个只读路径的MCP服务端，暴露LightRAG后端给MCP兼容的代理** （Claude Code, Cursor, Claude Desktop, 任何MCP客户端）。Workspace-aware，具有每个主机的允许列表和注册驱动的多租户模型，因此一个桥接进程可以为多个LightRAG实例服务。
用于[选择企业代理的记忆](https://agorokh.github.io/applied-ai-research/2026-05-19_choosing-memory-for-enterprise-agents/) 研究，作为SDLC历史语料库的实时读取路径。
```
┌─────────────────────┐ 标准输入输出MCP ┌─────────────────────┐ HTTP /query ┌─────────────────┐
│ MCP客户端 │──────────────────────▶│ 智能记忆MCP服务端 │──────────────────▶│ LightRAG │
│ (Claude Code等) │ │ (此服务端) │ │ 工作空间A │
└─────────────────────┘ │ │ └─────────────────┘
│ fleet_registry.toml│ ┌─────────────────┐
│ + 允许列表 │──────────────────▶│ LightRAG │
│ │ │ 工作空间B │
└─────────────────────┘ └─────────────────┘
```
## 它做什么
- **只读。** 没有写入LightRAG后端（摄入保持在单独的摄入管道中）。桥接器仅调用`POST /query`和`GET /health`。
- **工作空间感知。** 每个MCP工具调用都带有`workspace`参数；桥接器从fleet registry TOML文件中查找工作空间的HTTP端点。
- **每个主机的允许列表。** `AGENTIC_MEMORY_ALLOWED_WORKSPACES`环境变量限制此进程可以路由到的工作空间。不同的主机机器看到不同的工作空间子集。
- **审计跟踪。** 每个工具调用都会记录（默认情况下会删除提示；`AGENTIC_MEMORY_LOG_PROMPTS=1`包含）。
- **HTTP连接池。** 一个单独的共享`httpx.AsyncClient`处理所有工作空间（可通过环境变量调整；见下文）。
## 通过MCP公开的工具
| 工具 | 功能 | LightRAG端点 |
|---|---|---|
| `query_knowledge_graph` | 查询，支持`mix`、`semantic`、`keyword`、`global`、`hybrid`、`local`或`naive`模式。返回带有`http_status`、`ok`和`result`的JSON。 | `POST /query` |
| `verify_server_health` | 可达性检查（`workspace="*"`探测所有可见工作空间）。 | `GET /health` / `GET /` |
| `get_graph_metadata` | 每个工作空间的`/health`负载。 | `GET /health` |
| `check_indexing_status` | 具有操作员友好标签的`/health`负载。 | `GET /health` |
| `list_workspaces` | 允许列表过滤后的注册表元数据（每行`query_supported`标志）。 | （仅限注册表） |
### `query_knowledge_graph` 参数
| 参数 | 默认值 | 备注 |
|---|---|---|
| `prompt` | （必填） | 转发到LightRAG；最大32,000字符。 |
| `workspace` | 自动选择一个可见的工作空间 | 当有多个工作空间可见时必填。 |
| `search_mode` | `mix` | `semantic` → LightRAG `local`; `keyword` → `naive`。 |
| `limit` | `60` | 限制序列化MCP JSON（~`limit × 400`字符），而不是LightRAG `top_k`。 |
| `context_only` / `prompt_only` | `false` | 映射到LightRAG `only_need_context` / 分片包含。 |
没有`set_active_workspace` — 每个工具调用都显式传递`workspace`。
## 快速开始
```bash
# 1. 安装
pip install -e .
# 2. 复制并编辑示例注册表（架构v2）
cp examples/fleet_registry.example.toml ./fleet_registry.toml
$EDITOR fleet_registry.toml
# 局域网/私有IP需要：
export AGENTIC_MEMORY_ALLOW_PRIVATE_ENDPOINTS=1
export AGENTIC_MEMORY_REGISTRY_PATH=$PWD/fleet_registry.toml
# 3. （可选）为此主机允许列表
export AGENTIC_MEMORY_ALLOWED_WORKSPACES=my_workspace_a,my_workspace_b
# 4. 运行MCP服务端（标准输入输出）
agentic-memory-mcp
# 或：python -m agentic_memory.server
```
通过将以下内容添加到`.mcp.json`来从Claude Code连接：
```json
{
"mcpServers": {
"agentic-memory": {
"command": "agentic-memory-mcp",
"env": {
"AGENTIC_MEMORY_REGISTRY_PATH": "/abs/path/to/fleet_registry.toml",
"AGENTIC_MEMORY_ALLOW_PRIVATE_ENDPOINTS": "1"
}
}
}
}
```
## 环境变量
| 变量 | 是否必填 | 含义 |
|---|---|---|
| `AGENTIC_MEMORY_REGISTRY_PATH` | 是 | `fleet_registry.toml`的路径（优先使用绝对路径）。 |
| `AGENTIC_MEMORY_ALLOWED_WORKSPACES` | 否 | 以逗号分隔的工作空间ID。为空 = 所有**启用**的行。 |
| `AGENTIC_MEMORY_ALLOW_PRIVATE_ENDPOINTS` | 否 | `1` / `true`允许环回和RFC1918端点在注册表中。 |
| `AGENTIC_MEMORY_LOG_PROMPTS` | 否 | 在审计JSON中记录原始提示（避免在共享日志栈中）。 |
| `AGENTIC_MEMORY_LOG_LEVEL` | 否 | Python日志级别（默认`INFO`）。 |
| `AGENTIC_MEMORY_HTTP_MAX_CONNECTIONS` | 否 | 共享httpx池大小（默认`64`）。 |
| `AGENTIC_MEMORY_HTTP_MAX_KEEPALIVE` | 否 | 保持连接（默认`16`）。 |
| `AGENTIC_MEMORY_QUERY_READ_TIMEOUT_S` | 否 | 上游HTTP读取超时（默认`120`）。 |
| `AGENTIC_MEMORY_MAX_PROBE_CONCURRENCY` | 否 | 启动/ `verify_server_health("*")`的并行度（默认`8`）。 |
| `AGENTIC_MEMORY_JSON_PRETTY` | 否 | 设置Truthy时，漂亮地打印MCP工具JSON。 |
## Fleet注册表架构（v2）
支持的读取器版本：`"1"`和`"2"`。写入器应发出`schema_version = "2"`。
```toml
schema_version = "2"
[[vaults]]
id = "my_workspace_a"
endpoint = "http://localhost:8020"
backend = "lightrag" # 目前只有lightrag是可查询的
enabled = true
allowed_modes = ["mix", "hybrid", "semantic"] # 可选；默认 = 所有模式
origin = "repo-product" # 可选
graph_namespace = "..." # 可选；仅用于graphiti元数据
```
- **`backend = "graphiti"`** 行在`list_workspaces`中列出，但**无法查询**，直到存在Graphiti读取路径。
- **`allowed_modes`** 在设置时限制每个工作空间的`search_mode`；空列表拒绝所有模式。
- 端点不得嵌入凭证。元数据主机（例如云元数据URL）被阻止。
单独的 upstream 管道负责从您的fleet声明中生成此文件。
## 信任模型
- **只读桥接器** — 仅在配置的端点上进行`POST /query`和`GET /health`。
- **主机允许列表** — `AGENTIC_MEMORY_ALLOWED_WORKSPACES`限制每个进程可见的工作空间。
- **审计日志** — stderr上的结构化JSON；除非设置`AGENTIC_MEMORY_LOG_PROMPTS`，否则提示会被哈希。
### 运行安全
- **没有MCP或上游HTTP身份验证** — 隔离桥接器进程并限制谁可以编辑`fleet_registry.toml`。
- **注册表端点是能力URL** — 桥接器将获取配置的任意URL（SSRF风险）。在生产环境中使用网络出口控制；仅在本地开发时设置`AGENTIC_MEMORY_ALLOW_PRIVATE_ENDPOINTS`。
- **工具响应可能包含内部URL** 来自`list_workspaces` / 健康工具。
参见[SECURITY.md](SECURITY.md)以获取协调披露和强化说明。
## 为什么存在
大多数智能记忆桥接器要么将您锁定到一个后端每个进程，或者在读取路径上公开写入能力。此桥接器故意相反：一个进程服务于多个工作空间，工作空间是每个调用的参数，写入路径超出了代理的范围。
## 开发
```bash
pip install -e ".[dev]"
pytest --cov=agentic_memory --cov-fail-under=73 -v
ruff check src tests
```
## 配套项目
- [**sdlc-dial-adapter**](https://github.com/agorokh/sdlc-dial-adapter) — Anthropic Messages API → OpenAI聊天补全翻译器。
- [**applied-ai-research**](https://github.com/agorokh/applied-ai-research) —从业者笔记引用此桥接器。
## 许可证
[Apache-2.0](LICENSE)。包含专利授权。
