graphmind

graphmind

graphmind 是一种小巧、持久的 Agent 记忆：一个知识图谱，你可以逐条添加事实，并在之后查询。你可以记录实体——人、地点、项目，以及任何有名称的事物——为每个实体指定类型，并逐步添加纯文本观察记录，再用带类型的关系将它们连接起来（“Alice — lives_in → Lisbon”）。整个图谱保存在磁盘上的一个 JSON 文件中，因此重启后记忆依然保留，并且文件易于阅读、比较差异和手动编辑。

无需运行数据库，也无需注册任何服务。图谱文件就是产品本身。

安装

npx @reneturcios/graphmind read

或者运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/graphmind

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。如果运行容器，请在工作目录上挂载卷，以便图谱文件能在多次运行之间保留。

图谱的存储位置

存储文件路径由环境变量 GRAPHMIND_FILE 指定，默认为当前工作目录下的 ./graphmind.json。服务（或 CLI 命令）启动时会加载该文件，每次更改后都会重写文件，因此磁盘上的文件始终包含完整的当前图谱：

{
  "entities": [
    { "name": "Alice", "entityType": "person", "observations": ["Lives in Lisbon"] }
  ],
  "relations": [
    { "from": "Alice", "to": "Lisbon", "relationType": "lives_in" }
  ]
}

CLI

CLI 提供读取和检查功能，操作的是 MCP 服务写入的同一个存储文件：

# Print the whole graph as JSON
graphmind read

# Print the subgraph matching a search term
graphmind search lisbon

# Point at a specific store file
GRAPHMIND_FILE=~/notes/graph.json graphmind read

graphmind --version

退出码：成功时为 0，无法读取或写入存储时为 1，用法错误时为 2。

MCP 服务

同一个可执行文件提供这两种功能。mcp 子命令会启动一个 stdio MCP 服务：

npx -y @reneturcios/graphmind mcp

MCP 客户端配置：

{
  "mcpServers": {
    "graphmind": {
      "command": "npx",
      "args": ["-y", "@reneturcios/graphmind", "mcp"],
      "env": { "GRAPHMIND_FILE": "/path/to/graphmind.json" }
    }
  }
}

工具

工具	输入	功能
create_entities	entities：{name, entityType, observations} 数组	添加名称尚未被占用的实体。已存在的名称会被跳过，已存储的实体保持不变。仅返回实际创建的实体。
create_relations	relations：{from, to, relationType} 数组	添加尚未存在的精确三元组关系。仅返回实际创建的关系。
add_observations	observations：{entityName, contents} 数组	向现有实体追加观察记录字符串，并跳过实体已有的字符串。按实体返回新增内容。
delete_entities	entityNames：字符串数组	移除指定实体，以及所有与其中任一实体相连的关系。
delete_observations	deletions：{entityName, observations} 数组	从指定实体中移除列出的观察记录字符串。
delete_relations	relations：{from, to, relationType} 数组	移除与给定精确三元组匹配的关系。
read_graph	（无）	返回整个图谱：所有实体和关系。
search_nodes	query：字符串	不区分大小写地搜索实体名称、类型和观察记录中的子字符串。返回匹配的实体，以及两端均匹配的关系。
open_nodes	names：字符串数组	返回指定实体及它们之间的关系。忽略未知名称。

值得了解的行为

• 名称就是身份标识。 实体由其名称标识；创建同名的第二个实体不会产生任何效果。要重命名，请先删除，再重新创建。
• 关系必须连接实际存在的端点。 create_relations 要求 from 和 to 实体都已存在；若其中一个不存在，整个调用都会失败——不会创建占位实体，因此拼写错误会立即显现，而不会悄悄破坏图谱。
• 观察记录按顺序构成集合。 添加实体已有的字符串不会产生任何效果；新字符串会按给定顺序追加。
• 只有删除实体会级联删除。 删除实体会移除其关系；删除观察记录或关系不会影响其他内容。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network
npm run dev     # run the CLI from source via tsx

许可证

MIT — 参见 LICENSE。