Graph-Mem

Graph-Mem MCP

为 AI Agent 和 IDE 提供持久化知识图谱记忆

Graph-Mem MCP 是一款通用 MCP 服务，通过知识图谱为任何 Agent 或 IDE 提供持久化、结构化记忆。它将图存储、语义向量搜索和多跳遍历整合在一个软件包中——安装后将其添加到 MCP 配置中，Agent 就能获得可跨会话保留的记忆。凡是支持 MCP 的地方都能使用它。

专为安全托管数据而构建

1055 项测试	基于暴力参考实现进行基于属性的测试，并对每个解析器进行模糊测试
mypy strict	已通过检查，并在 CI 中强制执行——不只是配置了而已
经过身份验证的 UI	主机和 Origin 允许列表及会话令牌；跨源写入会返回 403，并已通过运行中的服务验证
有界限制	每项遍历、搜索和列表响应都有具名且可配置的上限，并会报告截断情况
诚实的文档	性能声明附有测量数据和可复现的基准测试；已知差距均有记录

兼容对象

graph-mem 是标准 MCP 服务，因此可与任何兼容 MCP 的 Agent、IDE 或框架配合使用。graph-mem install 还会将技能 文件直接写入以下 13 种工具的正确位置，路径均依据 厂商自己的文档核实：

Claude Code	OpenCode	Cursor	Windsurf	Codex CLI
Gemini CLI	GitHub Copilot	Amp	Kiro	Roo Code
Continue	Antigravity	Droid (Factory)	添加你的工具 →

使用其他工具？只需使用下方的 MCP 配置；技能文件只是便捷选项，并非必需。将你的 Agent 添加到安装程序只需采用有文档说明的路径，并编写约 10 行代码——请参阅 添加 Agent。

---

这是什么？

AI Agent 会忘记不同会话之间的所有内容。它们会重新读取文件、重新发现架构，并重复犯错。Graph-Mem MCP 通过提供持久化的项目级知识图谱解决了这个问题，任何兼容 MCP 的 Agent 都能读取和写入这些图谱。Agent 会在工作过程中逐步构建图谱——从每次对话中提取实体、决策和关系。它以标准 MCP 服务的形式运行，提供 28 种工具，可接入任何支持模型上下文协议的 Agent、IDE 或框架。

为什么选择图谱，而不仅仅是向量存储？

向量搜索能找到_相似_的内容，图谱能找到_关联_的内容。当 Agent 询问“哪些内容依赖于身份验证服务？”时，向量存储会返回提及身份验证的文本。知识图谱则会遍历实际的依赖关系边，返回所有上游使用者——即使它们的描述中从未提及“身份验证”。Graph-Mem 两者兼备：使用向量相似度进行模糊发现，使用图遍历执行结构化查询。

使用场景

• Agent 记忆 — 为任何 AI 编码 Agent 提供跨会话的持久上下文
• IDE 集成 — 将知识图谱工具添加到 Cursor、Windsurf、Copilot 或任何支持 MCP 的 IDE
• 构建 Agent — 构建自定义 AI Agent 和工作流时，将其用作记忆层
• 研究与知识管理 — 构建支持语义搜索的结构化知识库
• 多项目上下文 — 借助多图谱支持，为每个项目维护独立的知识图谱

---

快速开始

1. 安装：

pip install graphmem-mcp

或者无需安装即可运行 — uvx 会获取并隔离它，就像 npx 对 Node 所做的那样：

uvx --from graphmem-mcp graph-mem server

它已列入官方 MCP Registry， 名称为 io.github.Sathvik-1007/graphmem-mcp，因此支持 MCP 的客户端可以直接发现并 安装它。

2. 为你的 Agent 安装技能：

graph-mem install claude       # Claude Code
graph-mem install opencode     # OpenCode
graph-mem install codex        # Codex CLI
graph-mem install gemini       # Gemini CLI
graph-mem install cursor       # Cursor
graph-mem install windsurf     # Windsurf
graph-mem install amp          # Amp
graph-mem install antigravity  # Antigravity
graph-mem install copilot      # GitHub Copilot
graph-mem install kiro         # Kiro
graph-mem install roocode      # Roo Code
graph-mem install continue     # Continue
graph-mem install droid        # Droid (Factory)

这会写入一个技能文件，教你的 Agent 如何使用全部 28 个 MCP 工具 — 何时搜索、何时添加实体、命名约定以及常见工作流。

3. 配置 MCP，将以下内容添加到 Agent 的 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"
      ]
    }
  }
}

就是这样。你的 Agent 现在拥有持久记忆。让它运行 read_graph() 进行验证。

---

单条提示词完成设置

将此内容粘贴到 Agent 的聊天中即可立即开始：

I want you to give yourself persistent memory using graph-mem. Run the following:

pip install graphmem-mcp
graph-mem install claude    # or: opencode, codex, gemini, cursor, windsurf, amp,
                            #     antigravity, copilot, kiro, roocode, continue, droid

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 graphmem-mcp
graph-mem server

选项 2：uvx（无需预先安装）

uvx --from graphmem-mcp graph-mem server

uvx 会将软件包下载到隔离环境中，并通过一条命令运行它。除了 uv 之外，无需预先安装任何内容。

选项 3：从源码安装

git clone https://github.com/Sathvik-1007/GraphMem-MCP
cd graph-mem
pip install -e ".[full,dev]"
graph-mem server

可选附加项

pip install "graphmem-mcp[embeddings]"   # sentence-transformers for local embeddings
pip install "graphmem-mcp[onnx]"         # ONNX runtime for embedding inference
pip install "graphmem-mcp[ui]"           # aiohttp for interactive graph visualisation
pip install "graphmem-mcp[full]"         # all of the above

---

工具

Graph-Mem 提供 28 个 MCP 工具 — 十个用于写入，九个用于读取，四个用于维护，四个用于多图谱管理，还有一个实用工具。所有基本元素都支持完整的 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	全面质量检查——未连接的节点、缺失数据、薄弱链接。返回结构化检查结果及渲染后的 report 字段

可视化（1）

工具	描述
open_dashboard	启动交互式图可视化界面并返回其 URL

多图工具（4）

工具	描述
list_graphs	列出 .graphmem/ 目录中所有已命名的图及其实体、关系和观测数量
create_graph	创建新的已命名图（.graphmem/<name>.db）
switch_graph	切换当前活动图——热切换存储、搜索和图引擎
delete_graph	删除已命名的图（无法删除当前活动图）

多图存储：每个已命名的图都是 .graphmem/ 中独立的 SQLite 数据库。默认图为 graph.db。在 CLI 命令中使用 --graph <name> 以指定目标图。

---

架构

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 和 streamable-http），并将所有数据存储在项目根目录下的 .graphmem/graph.db 中。数据库文件可移植——可在不同计算机之间复制、提交到版本控制，或像其他文件一样备份。

延伸阅读

文档	内容
工作原理	数据模型、搜索流程、遍历、实体解析、存储布局、请求流程
架构	设计背后的原因——关键决策、相应代价及实测基线
安全	威胁模型、MCP 与浏览器的信任边界，以及明确不在范围内的内容
贡献指南	本地设置以及 CI 强制执行的检查

---

MCP 集成

Graph-Mem MCP 是标准 MCP 服务。它通过 Model Context Protocol 与你的 Agent 通信（默认使用 stdio，也支持 SSE 和 streamable-http），并提供 28 个由 Agent 直接调用的工具——与调用其他 MCP 工具的方式相同。它开箱即兼容所有 MCP 兼容的 Agent、IDE 和框架。

要验证其是否正常工作，请让你的 Agent 运行 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

graph-mem ui 打印的 URL 中包含一个会话令牌——请将其视为密码。仪表板会读取并写入图谱，因此 API 要求请求在自定义标头中携带该令牌，并会拒绝 Origin 或 Host 与其绑定的界面不匹配的请求。若没有这些检查，你在 UI 运行期间访问的任何网站都可能改写你的知识图谱。详情请参阅 SECURITY.md。

open_dashboard MCP 工具也会启动此 UI 服务，并将 URL 返回给你的 Agent。它始终绑定到 localhost：绑定地址被刻意设为非工具参数，因此遭到提示词注入的 Agent 无法将你的图谱发布到网络上。

仪表板功能：

• 力导向图画布，带实时物理模拟
• 实体类型筛选——通过侧边栏复选框切换实体类型的可见性
• 点击聚焦——点击图谱或侧边栏中的节点，即可立即将其居中并缩放至该节点
• 实体内联编辑——点击详情面板中的任意字段（名称、类型、描述），即可就地编辑
• 属性管理——通过每行控件为各实体添加、编辑和删除单个属性
• 观察项管理——通过确认对话框和内联编辑添加、编辑和删除观察项
• 关系导航——点击相关实体即可在图谱中导航
• 实体创建和删除——从侧边栏创建新实体，从详情面板的危险操作区域确认并删除实体
• 混合搜索——跨所有实体进行语义 + 关键词搜索
• 图谱选择器——无需重启服务即可在命名图谱间切换
• 物理参数控制——实时调整弹簧、斥力、阻尼和重力
• 键盘快捷键——Space（重新加热）、F（适应视图）、Escape（取消选择）

---

数据存储

默认情况下，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 环境变量	export GRAPHMEM_DB_PATH=/tmp/test.db	存储在该路径
默认	（无）	存储在相对于 CWD 的 .graphmem/graph.db

优先级顺序： --db > --project-dir > GRAPHMEM_DB_PATH 环境变量 > 默认值。

如果 .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	项目根目录；数据库位于 <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 嵌入后端（需要 optimum[onnxruntime]）	关闭
--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)

技能的安装位置

以下所有路径均依据供应商当前文档列出。无法引用其安装位置的 Agent 不会列在此处——猜测路径会报告成功、写入文件，但 Agent 永远不会读取它，这比不支持更糟。正因如此，有 6 个 Agent 被移除。

Agent	项目路径	用户级路径	写入方式	来源
claude	.claude/skills/graph-mem/SKILL.md	~/.claude/skills/graph-mem/SKILL.md	独立文件	文档
opencode	.opencode/skills/graph-mem/SKILL.md	~/.config/opencode/skills/graph-mem/SKILL.md	独立文件	文档
codex	AGENTS.md	~/.codex/AGENTS.md	章节	文档
gemini	GEMINI.md	~/.gemini/GEMINI.md	章节	文档
cursor	.cursor/rules/graph-mem.mdc	—	独立文件	文档
windsurf	.windsurf/rules/graph-mem.md	~/.codeium/windsurf/memories/global_rules.md	独立文件	文档
amp	.agents/skills/graph-mem/SKILL.md	~/.config/agents/skills/graph-mem/SKILL.md	独立文件	文档
antigravity	AGENTS.md	~/.gemini/AGENTS.md	章节	文档
copilot	.github/copilot-instructions.md	—	章节	文档
kiro	.kiro/steering/graph-mem.md	~/.kiro/steering/graph-mem.md	独立文件	文档
roocode	.roo/rules/graph-mem.md	~/.roo/rules/graph-mem.md	独立文件	文档
continue	.continue/rules/graph-mem.md	—	独立文件	文档
droid	AGENTS.md	~/.factory/AGENTS.md	章节	文档

目标文件为共享文件的 Agent——AGENTS.md、GEMINI.md、 .github/copilot-instructions.md 和 Windsurf 的全局规则——会在其中写入带分隔标记的 章节。文件中已有的内容会保留；重新安装时会替换该章节，而不是再追加一份。

想支持其他 Agent？请参阅 添加 Agent——只需提供有文档依据的 路径和大约 10 行代码。

图谱管理

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.db。MCP 工具 list_graphs、create_graph、switch_graph 和 delete_graph 为 Agent 提供运行时图谱管理功能。

---

配置

所有设置均为可选项。默认配置开箱即用。每项设置都可通过 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	HuggingFace 模型 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 传输协议

---

性能

提供实测数据，而非形容词。运行 python benchmarks/bench_traversal.py 可复现遍历数据；完整表格见 docs/ARCHITECTURE.md。

遍历 — 使用带全局已访问集合的广度优先搜索，每跳执行一次索引邻接查询。一个稠密的 60 节点图遍历至深度 6 仅需 5 ms。显而易见的递归 CTE 实现会枚举所有简单路径：在一个 14 节点图上，它耗时 6.4 秒并生成 1,409,006 条中间记录，才返回与 BFS 在 1 ms 内返回的相同 13 个实体。

图画布 — Barnes-Hut 力模拟（θ = 0.9）。2000 个节点可达 215 fps；5000 个节点（API 自身的上限）可达 80 fps。此前的全点对实现分别只能达到 30 fps 和 3.7 fps。与精确求和相比，近似误差的 RMS 为 1.30%，且收敛后的布局等效。

存储

• 使用 WAL 日志和 PRAGMA 调优，实现并发读取和内存映射 I/O，因此大型数据库不会按比例消耗 RAM
• 使用单个连接，最外层事务持有写锁，并使用 BEGIN IMMEDIATE，避免读到写的升级无法重试而失败
• 批量执行批处理操作，且每个 IN (...) 均拆分为低于 SQLite 绑定变量上限的块

嵌入

• 按 (hash, model) 为内容哈希缓存键，因此两个模型可以共存而不会相互覆盖；支持 LRU 淘汰，以及批量读写
• 启动时在后台线程中延迟加载模型，并在工作线程中运行推理，两者都不会阻塞事件循环
• 安装 optimum[onnxruntime] 并设置 --use-onnx 后，可选用 ONNX 后端；若不可用则回退到 PyTorch。此功能默认关闭；本项目未发布其基准测试，因此不在此声称有任何提速。

上限 — 每项遍历、搜索和列表响应都受有名称且可配置的上限约束；达到上限时，响应会明确说明，而不是静默返回部分结果。

---

开发

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

---

Star 历史

---

许可证

MIT