全本地运行的个人知识图谱工具：3D 可视化、AI 文档导入、OWL 推理、向量混合检索、Git 级保存点、MCP Server。数据始终存放在本机 SQLite 中。
- 个人知识管理：读书笔记、学习摘录沉淀为可检索、可视化的关系网络，越用越密
- 研究与考证：人物、事件、地点、时间线的梳理与追溯（历史考据、家谱、案件梳理、情报分析）
- 创作设定库：小说、剧本、游戏世界观的角色关系、组织架构、地理设定统一管理
- 文档资产化：批量导入 Markdown / PDF / Word，AI 自动抽取实体关系，零手工建库
- 离线分享：单文件 HTML 查看器发给他人浏览器直接打开；整库 .db 一键交接
| 模块 | 说明 |
|---|---|
| 3D 可视化 | three.js 力导向布局，实体按 4 大类区分形状/颜色，关系按 5 大类区分线型；支持中心层级视图（可调层数）、视图主题自定义、实体图片绑定与灯箱 |
| AI 文档导入 | 调用 OpenCode CLI 将 Markdown/PDF/Word 等文档抽取为三元组并自动导入（分块+保存点对齐，防重复导入） |
| OWL 推理 | 按 传递/对称/逆 三类规则动态推导隐性关系（不入库），可配置 data/ontology.json，前端一键叠加显示并可查看推导链 |
| 混合检索 | 语义向量（默认硅基流动 BAAI/bge-m3，可换任意 OpenAI 兼容接口）+ 关键词检索，RRF 融合排序 |
| 迷你 Cypher | 只读关系查询：MATCH (a)-[r:互动]->(b) WHERE a.name contains 郑和 RETURN a.name, r.name LIMIT 10 |
| 数据资产 | 实体图片（本地存储，独立表）、RDF Turtle 导出、SQLite 整库导出/导入（自动备份保存点）、单文件只读网页另存 |
| 保存点 | 每次合规写入自动打 Git 保存点，违规写入自动回滚到上个合规版本；可一键回溯任意历史版本 |
| MCP Server | 零依赖 stdio JSON-RPC + Streamable HTTP，一键连接命令接入 Claude Desktop / OpenCode 等支持 MCP 的客户端 |
| 轻量 SDK | 零依赖 HTTP 客户端（sdk/kg-client.mjs），程序/Agent 不经 MCP 直接调用全部功能；文档人类与 Agent 合读（/sdk） |
| CLI 工具集 | kgctl 多子命令（stats/get/list/search/cypher/ego/path/inference/ops/export...），无需服务运行即可读写图谱；文档（/cli） |
| 双端适配 | 桌面端完整面板；手机端单行工具栏+抽屉面板+文件菜单 |
环境要求：Node.js >= 22.5（使用内置 node:sqlite），Windows / macOS / Linux 均可，无需数据库安装。
npm i -g local-knowledge-graph
kg一条命令安装，一条命令启动（服务就绪后自动打开浏览器）。数据保存在用户目录 ~/.local-knowledge-graph/，升级（kg 内一键更新或 npm i -g local-knowledge-graph@latest）不影响数据。也可以免安装试用：npx local-knowledge-graph。
启动参数：kg --port 3000 --host 127.0.0.1 --data <目录> --no-open（详见 kg --help）。npm start / node server.js 同样会在就绪后自动打开浏览器（环境变量 KG_NO_OPEN=1 禁止）；默认端口被占用时自动顺延（3000→3020），实际地址以启动窗口显示为准。
| 平台 | 操作 |
|---|---|
| Windows | 双击 start.bat |
| macOS | 双击 start.command（若提示无法打开：右键 → 打开；若提示无执行权限：终端执行一次 chmod +x start.command start.sh） |
| Linux | ./start.sh（首次可能需 chmod +x start.sh） |
脚本自动完成：Node 版本检查 → 首次自动安装依赖（仅 express，几秒）→ 启动服务 → 就绪后自动打开浏览器。此模式数据存放在项目内 data/ 目录，应用内"一键更新"走 git 快进拉取。Windows 下 start.bat 为前台窗口：窗口即服务本体，关闭窗口（或 Ctrl+C）即停止服务。
# 环境要求：Node.js >= 22.5（使用内置 node:sqlite）
npm install
# 启动（默认 http://localhost:3000）
npm startAI 导入功能需要安装 OpenCode CLI 并配置可用模型；其余功能（可视化/推理/检索配置/导出/MCP）无外部依赖。
server.js Express 服务与全部 API
lib/db.js SQLite 三表核心（entities/relations/operation_logs）+ 图片表 + 向量表 + 迷你Cypher
lib/validator.js 手工/AI 共用的合规校验（违规即整体拒绝，库保持上个合规版本）
lib/agent.js OpenCode CLI 封装（普通问答与文档导入两种模式）
lib/git.js data/ 目录 Git 保存点（差量提交与回溯）
lib/inference.js OWL 推理引擎（虚拟推导，不写库）
lib/embeddings.js 向量构建/检索（data/settings.json 存配置，已被 gitignore）
lib/rdf.js RDF Turtle 导出
lib/viewer.js 单文件只读网页查看器生成
mcp/server.js MCP Server（stdio + Streamable HTTP）
sdk/kg-client.mjs 轻量 SDK 客户端（零依赖 HTTP，程序/Agent 直连，不经 MCP）
SDK.md SDK 使用说明（人类与 Agent 合读；运行时 GET /sdk 在线查看）
bin/kgctl.js CLI 工具集（kgctl 多子命令；文档 CLI.md，运行时 GET /cli）
tools/ego.js 中心层级查询 CLI（只读）
public/index.html 单文件前端（无构建步骤）
data/ kg.db、ontology.json、settings.json、uploads/（gitignore，不出仓库）
vendor/ three.js 本地副本（全离线）
三张严格字段表 + 两张资产表：
entities(id, name, category, attributes, source, created_at)— category 枚举：物理实体/抽象实体/数值实体/时间实体，attributes 为扁平 JSONrelations(id, source_id, target_id, name, category, created_at)— category 枚举：归属/空间/时间/互动/属性operation_logs(id, op_type, snapshot, source, created_at)— 全部写入留痕，snapshot 为操作前后JSON快照entity_images/entity_embeddings— 图片与向量资产，不进入图谱保存点语义
API 一览（http://localhost:3000/api）
GET /meta 版本与计数
GET/POST /entities 实体 CRUD（PUT/DELETE /entities/:id）
GET/POST /relations 关系 CRUD（PUT/DELETE /relations/:id）
GET /graph 全图（含图片计数）
GET /graph/ego?center=&depth= 中心层级子图（depth 省略或 0 = 全部层级）
GET /inference?center= 推理关系（含推导依据与规则）
GET/PUT /ontology 推理规则配置
GET/PUT /embeddings/settings 检索配置（密钥不回传）
POST /embeddings/build 构建全量实体向量
POST /search 混合检索 {query, top_k}
POST /cypher 迷你 Cypher {query}
GET/POST /entities/:id/images 图片绑定（DELETE /images/:imgId）
POST /agent OpenCode 问答+kg-ops 写入
POST /agent/doc 文档批量导入（分块+保存点对齐）
GET/POST /git/history|savepoint|restore 保存点
GET /export/rdf RDF Turtle
GET /export/db?name= SQLite 整库导出
POST /graph/import SQLite 整库导入（自动备份+校验）
GET /export/html 单文件只读网页
AI 回答中输出 ```kg-ops 代码块（JSON 数组）即可写库，全部操作过校验、留日志、打保存点：
[
{"op":"add_entity","ref":"A","name":"大雁塔","category":"物理实体","attributes":{"朝代":"唐"}},
{"op":"add_relation","source_ref":"A","target_id":58,"name":"位于","category":"空间"}
]支持操作：add_entity / update_entity / delete_entity / add_relation / update_relation / delete_relation。
mcp/server.js 零外部依赖，stdio 传输；运行中的网页服务同时暴露 /mcp Streamable HTTP 端点（Bearer 令牌鉴权）。MCP 页签开启服务后，界面提供"一键连接"命令（令牌已内含，复制粘贴到终端即可）：
# 通用接入 / 连通性测试
npx -y mcp-remote http://localhost:3000/mcp --header "Authorization: Bearer <令牌>"
# Claude Code 一步注册
claude mcp add --transport http local-kg http://localhost:3000/mcp --header "Authorization: Bearer <令牌>"也可手动配置。以 Claude Desktop 为例（claude_desktop_config.json）：
{
"mcpServers": {
"local-kg": {
"command": "node",
"args": ["/absolute/path/to/local-knowledge-graph/mcp/server.js"],
"env": { "KG_MCP_READONLY": "1" }
}
}
}工具列表：kg_stats / kg_list_entities / kg_get_entity / kg_get_graph / kg_ego / kg_search / kg_cypher / kg_inference / kg_path / kg_digest / kg_export_rdf / kg_apply_ops。设 KG_MCP_READONLY=1 时拒绝全部写入。
打开前端"检索"页签，填入硅基流动（或任意 OpenAI 兼容 /embeddings 接口）的 API Key 后保存，点击"构建全量向量"。配置仅存本机 data/settings.json（该目录已被 .gitignore 排除）。
node tools/ego.js "郑和" # 全部层级
node tools/ego.js "郑和" 2 # 2 层内
node tools/ego.js --json 3 郑和 # JSON 输出退出码：0 成功 / 1 未找到 / 2 名称多义（附候选） / 3 参数错误。
- 除 AI 导入/问答需联网调用 OpenCode 外，其余功能完全离线
data/（数据库、密钥、图片）与node_modules/均不出仓库- 前端密钥输入框不回传真实值，服务端只存本地文件