使用说明
Graph Mem MCP
用于AI代理和IDE的持久知识图内存
Graph Mem MCP是一个通用的MCP服务器,通过知识图为任何代理或IDE提供持久的结构化内存。它将图存储、语义向量搜索和多跳遍历组合在一个包中——安装它,将其添加到MCP配置中,您的代理将获得在会话中生存的内存。它适用于MCP所做的任何地方。
使用
| Claude Code | OpenCode | Cursor | Windsurf | Codex CLI | Gemini CLI |
| GitHub Copilot | Amp | Kiro | Roo Code | Trae | Augment |
| Continue | Warp | KiloCode | Qoder | CodeBuddy | Droid (Factory) |
| Antigravity · and any MCP-compatible agent, IDE, or framework |
这是什么?
AI代理在会话之间会忘记一切。他们重新读取文件,重新发现架构,并重复错误。 Graph Mem MCP 通过提供任何兼容MCP的代理都可以读取和写入的持久的、每个项目的知识图来解决这个问题。该图随着代理的工作而有机地构建——从每个对话中提取实体、决策和关系。它作为一个标准的MCP服务器运行,带有28个工具,可以插入任何支持模型上下文协议的代理、IDE或框架。
为什么是图形,而不仅仅是矢量存储?
矢量搜索结果 相似的 东西。图表查找 连接的 东西。当代理询问“什么依赖于身份验证服务?”时,向量存储会返回提到身份验证的文本。知识图遍历实际的依赖边,并返回每个上游消费者,即使是那些在描述中从未提及“auth”的消费者。Graph Mem为您提供了两种功能:模糊发现的向量相似性,结构查询的图遍历。
用例
- 代理内存 --为任何AI编码代理提供跨会话的持久上下文
- IDE集成 --将知识图工具添加到Cursor、Windsurf、Copilot或任何启用MCP的IDE中
- 代理商大楼 --在构建自定义AI代理和工作流时用作存储层
- 研究与知识管理 --利用语义搜索构建结构化知识库
- 多项目背景 --使用多图支持为每个项目维护单独的知识图
快速开始
1.安装:
pip install graph-mem
2.为您的代理安装技能:
graph-mem install opencode # OpenCode
graph-mem install claude # Claude Code
graph-mem install cursor # Cursor
graph-mem install windsurf # Windsurf
graph-mem install codex # Codex CLI
graph-mem install gemini # Gemini CLI
graph-mem install copilot # GitHub Copilot
graph-mem install amp # Amp
graph-mem install kiro # Kiro
graph-mem install roocode # Roo Code
graph-mem install trae # Trae
graph-mem install augment # Augment
graph-mem install continue # Continue
graph-mem install warp # Warp
graph-mem install kilocode # KiloCode
graph-mem install qoder # Qoder
graph-mem install codebuddy # CodeBuddy
graph-mem install droid # Droid (Factory)
graph-mem install antigravity # Antigravity
这将编写一个技能文件,教您的代理如何使用所有28个MCP工具——何时搜索、何时添加实体、命名约定和常见工作流。
3.配置MCP 通过将此添加到代理的MCP配置中:
{
"mcpServers": {
"graph-mem": {
"command": "graph-mem",
"args": ["server"]
}
}
}
完全定制:
{
"mcpServers": {
"graph-mem": {
"command": "graph-mem",
"args": [
"server",
"--project-dir", "/path/to/my/project",
"--embedding-model", "sentence-transformers/all-mpnet-base-v2",
"--use-onnx",
"--cache-size", "20000",
"--log-level", "INFO"
]
}
}
}
就是这样。你的特工现在有持久记忆了。通过让它运行来验证 read_graph().
一键设置
将此粘贴到您的客服聊天室中以立即开始:
I want you to give yourself persistent memory using graph-mem. Run the following:
pip install graph-mem
graph-mem install opencode # or: claude, cursor, windsurf, codex, gemini, copilot, amp, kiro, roocode, trae, augment, continue, warp, kilocode, qoder, codebuddy, droid, antigravity
This installs a skill file that teaches you how to use all 28 MCP tools.
The server should already be configured in your MCP config. If not, add it:
{
"mcpServers": {
"graph-mem": {
"command": "graph-mem",
"args": ["server", "--project-dir", "/path/to/your/project"]
}
}
}
Now start using the knowledge graph:
1. read_graph() to see current state
2. search_nodes("relevant topic") to find existing knowledge
3. add_entities, add_relationships, add_observations as you learn things
4. update_observation / update_relationship to fix mistakes in-place
5. open_dashboard() to explore the graph visually in your browser
6. At session end, capture anything important you discovered
Your goal: build a rich knowledge graph of this project so future sessions
start with full context instead of from zero. Search before adding to avoid
duplicates. Be specific with entity names and types.
安装
选项1:pip(推荐)
pip install graph-mem
graph-mem server
选项2:uvx(零预安装)
uvx graph-mem server
uvx 将包下载到一个隔离的环境中,并在一个命令中运行它。除此之外无需预安装 紫外线.
选项3:来源
git clone https://github.com/Sathvik-1007/GraphMem-MCP
cd graph-mem
pip install -e ".[full,dev]"
graph-mem server
任选附件
pip install "graph-mem[embeddings]" # sentence-transformers for local embeddings
pip install "graph-mem[onnx]" # ONNX runtime for ~3x faster inference
pip install "graph-mem[ui]" # aiohttp for interactive graph visualisation
pip install "graph-mem[full]" # all of the above
工具
Graph Mem公开 28个MCP工具 --10个用于写入,9个用于读取,4个用于维护,4个负责多图管理,1个用于实用程序。对每个原语进行完整的CRUD操作:实体、关系和观察都可以创建、读取、更新和删除。
书写工具(10)
| 工具 | 说明 |
|---|---|
add_entities |
批量创建具有可选观测值的实体;名称冲突时自动合并;返回质量筛选提示 |
add_relationships |
在实体之间创建类型化的有向边;按最大权重合并重复项 |
add_observations |
为具有可选来源的实体附加事实陈述 |
update_entity |
就地修改实体名称、描述、属性或类型(使用碰撞检查重命名) |
update_relationship |
更改现有边的权重、类型或属性,而无需删除+重新创建 |
update_observation |
通过自动嵌入重新计算就地编辑观察文本内容 |
delete_entities |
删除具有级联关系、观察和嵌入的实体 |
delete_relationships |
删除实体之间的特定边,可选择按类型过滤 |
delete_observations |
通过所有权验证按ID删除特定观察结果 |
merge_entities |
组合重复实体:移动观测值和关系,消除重复项 |
阅读工具(9)
| 工具 | 说明 |
|---|---|
search_nodes |
基于RRF融合排名的混合语义+全文搜索 |
search_observations |
直接在观察文本内容上进行语义搜索 |
find_connections |
带方向和类型过滤器的多跳BFS图遍历 |
get_entity |
包含所有观察结果和关系的完整实体详细信息 |
list_entities |
使用可选类型筛选器浏览/分页所有实体 |
list_relationships |
使用实体、类型或组合过滤器浏览/分页关系 |
read_graph |
图形统计:计数、类型分布、最连通实体 |
get_subgraph |
提取种子实体周围的邻域子图 |
find_paths |
通过BFS找到两个实体之间的最短路径 |
维护工具(4)
| 工具 | 说明 |
|---|---|
graph_health |
健康统计:计数、热点、缺失描述、建议行动 |
compact_observations |
原子观测压缩——一步删除旧摘要并添加合并摘要 |
suggest_connections |
为要连接的节点查找语义相似的实体 |
audit_graph |
全质量筛查——断开连接的节点、缺失的数据、薄弱环节(纯文本报告) |
可视化(1)
| 工具 | 说明 |
|---|---|
open_dashboard |
启动交互式图形可视化UI并返回其URL |
多图工具(4)
| 工具 | 说明 |
|---|---|
list_graphs |
列出中的所有命名图形 .graphmem/ 包含实体/关系/观察计数的目录 |
create_graph |
创建一个新的命名图(.graphmem/<name>.db) |
switch_graph |
切换活动图——热交换存储、搜索和图引擎 |
delete_graph |
删除命名图(无法删除当前活动的图) |
多图存储:每个命名图都是一个单独的SQLite数据库
.graphmem/。默认图形为graph.db.使用--graph <name>在CLI命令上以特定图形为目标。
建筑
graph TD
Agent[Any MCP-Compatible Agent or IDE] --> Transport
subgraph Transport
STDIO[stdio]
SSE[SSE]
HTTP[streamable-http]
end
Transport --> Tools
subgraph Tools[Graph-Mem MCP Server — 28 MCP Tools]
Write[Write · 10 tools]
Read[Read · 9 tools]
Maint[Maintenance · 4 tools]
Graph[Multi-Graph · 4 tools]
UI[Dashboard · 1 tool]
end
Write --> Engines
Read --> Engines
Maint --> Engines
subgraph Engines
GE[GraphEngine]
SE[HybridSearch]
EE[EmbeddingEngine]
GT[GraphTraversal]
EM[EntityMerger]
end
Engines --> Storage
subgraph Storage[SQLite Storage]
DB[SQLite WAL]
VEC[sqlite-vec]
FTS[FTS5]
end
UI --> Dashboard[React SPA + aiohttp]
Dashboard --> DB
每个项目的所有内容都存在于一个SQLite数据库中。服务器通过MCP的标准stdio传输(也支持SSE和流式http)进行通信,并将所有数据存储在 .graphmem/graph.db 在你的项目根。数据库文件是可移植的——在机器之间复制它,将其签入版本控制,或像其他文件一样备份它。
有关详细的技术文档——数据模型、搜索管道、实体解析、存储架构和请求流图——请参阅 运作原理.
MCP集成
Graph Mem MCP是一个标准的MCP服务器。它通过模型上下文协议(默认情况下为stdio,也支持SSE和流式http)与您的代理通信,并公开代理直接调用的28个工具,就像它调用任何其他MCP工具一样。它适用于所有与MCP兼容的代理、IDE和框架。
要验证它是否正常工作,请让您的代理运行 read_graph() --它应该返回当前的图形统计信息。
图形可视化
graph-mem ui # open interactive graph explorer
graph-mem ui --no-open # start server without opening browser
graph-mem ui --port 9090 # use a specific port
graph-mem ui --graph harry-potter # open a specific named graph
这 open_dashboard MCP工具还会启动此UI服务器,并将URL直接返回给您的代理。
仪表板功能:
- 力导向图形画布 实时物理模拟
- 实体类型过滤 --通过侧边栏复选框切换实体类型的可见性
- 单击以聚焦 --单击图表或侧边栏上的节点,立即居中并缩放到它
- 内联实体编辑 --单击详细信息面板中的任何字段(名称、类型、描述)以就地编辑
- 物业管理 --使用每行控件为每个实体添加、编辑和删除单个属性
- 观测管理 --通过确认对话框和内联编辑添加、编辑和删除观察结果
- 关系导航 --单击相关实体以浏览图形
- 实体创建和删除 --从侧边栏创建新实体,从详细信息面板危险区域确认删除
- 混合搜索 --跨所有实体的语义+关键字搜索
- 图形选择器 --在命名图之间切换,而无需重新启动服务器
- 物理控制 --实时调整弹簧、斥力、阻尼和重力
- 键盘快捷键 --空间(再热)、F(适合查看)、逃生(取消选择)
数据存储
默认情况下,Graph Mem将其数据库存储在 .graphmem/graph.db 相对于当前工作目录。您可以通过以下方式控制:
| 方法 | 示例 | 结果 |
|---|---|---|
--project-dir |
--project-dir /home/user/myproject |
商店在 /home/user/myproject/.graphmem/graph.db |
--db |
--db /custom/path/memory.db |
商店就在那条路上 |
GRAPHMEM_DB_PATH env |
export GRAPHMEM_DB_PATH=/tmp/test.db |
那条路上的商店 |
| 默认值 | (无) | .graphmem/graph.db 相对于CWD |
优先级顺序: --db > --project-dir > GRAPHMEM_DB_PATH env是>默认值。
这 .graphmem/ 如果目录不存在,则会自动创建。添加 .graphmem/ 给你的 .gitignore 如果您不想在版本控制中跟踪数据库。
CLI 参考
服务器
graph-mem server # stdio transport (default)
graph-mem server --transport sse # SSE transport
graph-mem server --db /path/to/graph.db # custom database path
graph-mem server --project-dir /my/project # store memory in <dir>/.graphmem/
graph-mem server --project-dir /my/project --graph harry-potter # use named graph
# Embedding customization
graph-mem server --embedding-model sentence-transformers/all-mpnet-base-v2
graph-mem server --no-onnx --embedding-device cuda
graph-mem server --cache-size 50000
# Tuning
graph-mem server --search-limit 20 --max-hops 6
graph-mem server --log-level DEBUG
所有服务器选项:
| 标志 | 描述 | 默认值 |
|---|---|---|
--transport |
stdio, sse,或 streamable-http |
stdio |
--db |
SQLite数据库文件的路径 | .graphmem/graph.db |
--project-dir |
项目根;DB在 <dir>/.graphmem/graph.db |
CWD |
--graph |
命名图(解析为 <dir>/.graphmem/<name>.db) |
graph |
--host |
绑定地址(仅限SSE/HTTP) | 127.0.0.1 |
--port |
端口(仅限SSE/HTTP) | 8080 |
--embedding-model |
用于嵌入的HuggingFace模型ID | all-MiniLM-L6-v2 |
--use-onnx / --no-onnx |
强制ONNX运行时打开/关闭 | 自动检测 |
--embedding-device |
cpu 或 cuda |
cpu |
--cache-size |
嵌入LRU缓存最大条目 | 10000 |
--search-limit |
默认最大结果 search_nodes |
10 |
--max-hops |
默认最大深度 find_connections |
4 |
--log-level |
DEBUG / INFO / WARNING / ERROR / CRITICAL |
WARNING |
技能安装
graph-mem install <agent> # project-level install
graph-mem install <agent> --global # global/user-level install
graph-mem install <agent> --domain code # use domain overlay (code, research, general)
支持的代理: claude, opencode, cursor, windsurf, codex, gemini, copilot, amp, kiro, roocode, trae, augment, continue, warp, kilocode, qoder, codebuddy, droid, antigravity.
图形管理
graph-mem init # create .graphmem/ directory
graph-mem init --project-dir /my/project # create in specific directory
graph-mem init --graph research # create a named graph
graph-mem status # print graph statistics
graph-mem status --json # graph statistics as JSON
graph-mem status --graph research # status of a named graph
graph-mem export --format json # export entire graph
graph-mem export --output backup.json # export to file
graph-mem import graph.json # import graph from file
graph-mem validate # run integrity checks
所有管理命令均接受 --db, --project-dir,以及 --graph 用于针对特定数据库。
多图支持:使用 --graph <name> 使用存储为的命名图 .graphmem/<name>.db.没有 --graph,命令以默认值为目标 graph.dbMCP工具 list_graphs, create_graph, switch_graph,以及 delete_graph 为代理提供运行时图管理。
配置
所有设置都是可选的。默认值开箱即用。每个设置都可以通过CLI标志进行控制(请参阅 graph-mem server --help)环境变量,或两者兼而有之。CLI标志优先于环境变量,环境变量优先于默认值。
| 环境变量 | CLI标志 | 默认值 | 描述 |
|---|---|---|---|
GRAPHMEM_DB_PATH |
--db |
.graphmem/graph.db |
数据库文件路径 |
GRAPHMEM_BACKEND_TYPE |
-- | sqlite |
存储后端 |
GRAPHMEM_EMBEDDING_MODEL |
--embedding-model |
all-MiniLM-L6-v2 |
拥抱脸部模型ID |
GRAPHMEM_USE_ONNX |
--use-onnx / --no-onnx |
false |
如果可用,请使用ONNX运行时 |
GRAPHMEM_EMBEDDING_DEVICE |
--embedding-device |
cpu |
推理装置(cpu 或 cuda) |
GRAPHMEM_CACHE_SIZE |
--cache-size |
10000 |
嵌入缓存最大条目 |
GRAPHMEM_SEARCH_LIMIT |
--search-limit |
10 |
默认搜索结果限制 |
GRAPHMEM_MAX_HOPS |
--max-hops |
4 |
默认最大遍历深度 |
GRAPHMEM_LOG_LEVEL |
--log-level |
WARNING |
记录冗长 |
GRAPHMEM_TRANSPORT |
--transport |
stdio |
MCP传输协议 |
演出
- WAL模式+PRAGMA调谐 --具有快速写入、优化日志和缓存设置的并发读取
- ONNX优化嵌入 --推理速度比默认PyTorch快3倍,具有自动回退功能
- 内容哈希嵌入缓存 --相同的文本永远不会嵌入两次
- 背景模型预热 --在启动过程中将模型加载嵌入到后台线程中
- 无阻塞延迟加载 --模型载荷通过
asyncio.to_thread因此嵌入调用永远不会阻塞事件循环 - 螺纹安全双重检查锁紧 --嵌入式引擎的安全并发访问
- 存储器映射 --大型数据库保持快速运行,而不会消耗成比例的RAM
- 批处理事务 --批量操作在单个事务中执行
- 弹性事务嵌套 --基于保存点的嵌套,故障时自动恢复深度
- 自动筛选 —
add_entities返回质量提示(缺少描述/观察),以便代理可以自我改进
发展
git clone https://github.com/Sathvik-1007/GraphMem-MCP
cd graph-mem
# Using uv (recommended)
uv venv
uv pip install -e ".[full,dev]"
# Or using pip
python -m venv .venv
source .venv/bin/activate
pip install -e ".[full,dev]"
运行测试
pytest # all tests
pytest tests/test_graph/ # graph engine tests
pytest tests/test_server/ # MCP server tool tests (all 28 tools)
pytest tests/test_cli/ # CLI command tests
pytest tests/test_models/ # data model tests
pytest tests/test_semantic/ # search + vector tests
pytest tests/test_storage/ # storage backend tests
pytest tests/test_db/ # database + migration tests
pytest tests/test_utils/ # config, logging, ID generation tests
pytest -x -q # stop on first failure, quiet output
