kg

kg - 面向 AI 助手的本地知识图谱

Beta - API 仍可能发生变化，也预计还会存在一些错误。

kg 为你的 AI 助手提供持久、结构化、可编辑的项目记忆，并以知识图谱的形式存储在本地。

你不必只依赖文档分块检索，还可以将架构、决策、事件、规则、依赖项和工作流保存在图谱中，方便阅读、审查并与 Git 协作。

当你希望助手跨会话理解现有项目，而不是每次都从零开始时，就可以使用它。

为什么要用它

• 持久记忆 — 在不同对话之间保留项目知识
• 结构化，而非模糊 — 直接检查节点、边、事实和知识缺口
• 可编辑、可审查 — 将图谱保存为 *.kg 文件，并生成易读的差异
• 本地优先 — 项目记忆以便于 Git 管理的格式保存在你的设备上
• 兼容 MCP 客户端 — 将其作为本地 stdio MCP 服务连接

为什么不直接用 RAG

经典 RAG 擅长从文档中检索文本块。

当你需要以下功能时，kg-mcp 会更合适：

• 稳定的项目记忆，而非反复检索
• 明确的事实、关系和依赖项
• 在与助手实际协作时更新图谱
• 可以检查、版本管理、比较差异并持续改进的内容

安装

从 crates.io 安装

cargo install kg-cli

通过脚本安装

推荐的安装方式：

curl -sSL https://raw.githubusercontent.com/nnar1o/kg/master/install.sh | sh

你也可以从 GitHub Releases 下载预编译的二进制文件。

将 kg-mcp 连接到你的 AI 客户端

将 kg-mcp 添加为本地 stdio MCP 服务。

配置示例：

{
  "mcpServers": {
    "kg": {
      "command": "/absolute/path/to/kg-mcp"
    }
  }
}

之后：

1. 重启你的 AI 客户端，
2. 确认 kg MCP 服务可用，
3. 开始使用下方的提示词。

完整的 MCP 配置和参考文档：docs/mcp.md

SCL 快速入门

kg 支持简短、动词优先的英文命令（SCL — 简易命令语言）。 系统会根据你的配置自动确定当前活动图谱。

find "compressor defrost"
get concept:refrigerator
add concept:smart_fridge --name "Smart Fridge" --description "Connected refrigerator"
modify concept:smart_fridge --importance 0.9
remove concept:old_idea
connect process:compressor_control TRIGGERS process:auto_defrost
disconnect process:compressor_control TRIGGERS process:auto_defrost
list nodes
stats
use fridge
help

核心动词

动词	功能
find <query>	按文本搜索节点
get <id>	获取一个节点
add <id> --name "Name"	创建节点（根据 ID 前缀推断类型）
modify <id> --field value	更新节点字段
remove <id>	删除节点
connect <src> <REL> <dst>	创建一条边（别名：add edge）
disconnect <src> <REL> <dst>	删除一条边（别名：remove edge）
list nodes|edges|types|relations|graphs	列出图谱内容
stats	显示图谱统计信息
use <graph>	切换活动图谱
help [verb]	获取某个动词或全部动词的帮助
feedback <uid> yes|no|nil|pick <n>	对搜索结果提供反馈
strict	禁用后续行的默认值

ID

格式：<type>:snake_case — 例如 concept:fridge、bug:door_seal、process:compressor_cycle。

关系

HAS USES STORED_IN TRIGGERS CREATED_BY AFFECTED_BY AVAILABLE_IN DOCUMENTED_IN DEPENDS_ON TRANSITIONS DECIDED_BY GOVERNED_BY READS_FROM

提示

• 标志放在位置参数之后。多词值请加引号。
• 使用 ; 或换行分隔命令。以 # 开头的行是注释。
• 使用 use <graph> 在脚本中切换图谱。
• 规范的 kg <graph> node find ... 命令仍可作为备用方式使用。
• 完整的 SCL 参考文档：docs/scl.md

生成图谱

这是新项目的首个工作流：请助手根据你的文档创建或扩展图谱。

默认情况下，图谱存储在 ~/.kg/graphs 中，文件扩展名为 *.kg。

最简提示词：

You are connected to kg-mcp.

Project graph name: payments

Build or extend this graph from the project documentation I provide.
Use `payments` as the graph name for all graph operations.

Only add facts grounded in source material.
If an important fact is missing and can be inferred safely from the provided docs, update the graph.
If something is ambiguous, ask or record it as a note instead of inventing facts.

包含文档的提示词示例：

Use kg-mcp to build or extend the `payments` graph from these documents:
- docs/payments/overview.md
- docs/payments/retries.md
- docs/payments/providers.md

Only add facts grounded in the documents.
If something is ambiguous, keep it out of the graph or record it as a note.
When you finish, summarize what was added, what remains unclear, and what document should be ingested next.

此工作流的较长提示词：docs/ai-prompt-graph-from-docs.md

如需查看现成的仓库示例，请运行 cargo run --bin repo-example，从此仓库生成 repo-example.kg。

为目录自动生成图谱

kg 可以自动将现有文件夹转换为图谱。它会扫描目录树，识别多种常见文件类型，提取 Rust、Java、JavaScript/TypeScript、Python 和 C/C++ 的符号，并将生成的结构与手动创建的图谱分开保存。

对于类似 Markdown 的文档，它还会创建文档（GDOC）和章节（GSEC）节点，并包含章节内容。

无需手动建模所有内容，即可快速获取代码库或工作区的实用概览。生成的索引保存在本地，可刷新，也可以安全地从 git 中忽略。

示例：

cargo run --bin repo-example

此命令会从此仓库生成 repo-example.kg，作为本地演示。

向助手询问图谱中的事实

图谱创建完成后，常规工作流是请助手检查图谱，并根据图谱回答问题。

提示词示例：

Use kg-mcp to inspect my existing `payments` graph.

I want to understand:
- how payment authorization works,
- what triggers retries,
- which external providers are involved,
- which datastore reads and writes are part of the flow.

If the graph is missing critical information, say exactly what is missing.

其他实用问题：

• “payments 图谱中的哪些规则控制重试？”
• “哪些系统会向订单数据存储写入数据？”
• “此图谱中有哪些缺失或薄弱之处？”
• “哪些节点和边可以说明授权流程？”

通过助手添加或更新事实

你也可以在工作时请助手改进图谱。

提示词示例：

Use kg-mcp to review my existing `payments` graph.

Find:
- missing important nodes,
- weak descriptions,
- missing facts,
- suspicious or low-value edges.

Apply safe improvements where possible.
Only add facts grounded in the graph, the provided docs, or the current discussion.
If something is ambiguous, leave it out or add a note.

When you finish, summarize:
- what was wrong,
- what you changed,
- what still needs manual review.

如果你的主要系统提示词或项目提示词已告知助手该项目对应哪个图谱，此功能效果最佳。

最简项目级提示词：

You are connected to kg-mcp.
Project graph name: payments.
Use this graph for relevant reads and updates in this project.
If you notice important missing information that is grounded in the available docs or conversation context, update the graph as part of your work.
If uncertain, ask or add a note instead of inventing facts.

提示

项目配置（.kg.toml）

kg 会在当前目录及其父目录中查找 .kg.toml。

示例：

backend = "json" # json backend writes native .kg files by default
graph_dir = ".kg/graphs"
graph_dirs = ["../shared-graphs", "../team-graphs"]
nudge = 20
user_short_uid = "dev_01"

[graphs]
payments = "graphs/payments.kg"

说明：

• backend = "json" 是默认设置，优先使用 .kg 文本图谱。
• backend = "redb" 会将图谱存储在 .db 文件中。
• graph_dir 用于设置主要图谱目录。
• graph_dirs 用于添加其他目录，供 kg list 和图谱解析扫描。

将图谱保存在 Git 中

默认图谱目录为 ~/.kg/graphs。

你可以将该目录纳入 git 管理。

建议做法：

• 将主要的 *.kg 图谱文件纳入 git 管理；
• 忽略生成的伴随文件和本地操作文件；
• 将备份快照和事件日志视为本机历史记录，除非你明确希望对其进行版本管理。

建议的 .gitignore：

*.kglog
*.kgindex
*.event.log
*.migration.log
*.bak
*.bck.*.gz

实际使用中：

• *.kg 是主要图谱文件，通常需要审查并提交；
• *.kglog 是本地访问/反馈日志；
• *.kgindex 是生成的本地索引；
• *.event.log 是仅追加的本地变更时间线；
• *.bak 是上次写入前的磁盘版本；
• *.bck.*.gz 是定期生成的压缩备份快照；
• *.migration.log 是转换旧版图谱时生成的迁移报告。

*.kg 适合纳入 git 管理，并且经过专门设计，结构清晰，便于阅读差异以及多人协作时合并。

将图谱导出为 HTML

如需生成图谱的交互式 HTML 视图：

kg graph payments export-html --output payments.html

你可以保留生成的 HTML，作为当前图谱的可分享可视化快照。

文档

• docs/mcp.md - MCP 设置和工具参考
• docs/ai-prompt-graph-from-docs.md - 用于导入文档的较长提示词
• docs/build-graph-from-docs.md - 根据文档构建图谱的工作流
• docs/troubleshooting.md - 常见问题

联系方式

如有问题或反馈，请联系：[email protected]