kgn (Baobab00)

飞泰

英语 | 韩语

管理AI代理的知识——解析、存储、查询和协作。

KGN是一个开发人员友好的CLI+MCP服务器，适用于使用AI代理构建的团队。 在简单的YAML+Markdown文件中编写知识节点(.kgn)，定义关系 他们之间(.kge)，并让KGN处理存储、相似性搜索、冲突 检测和多代理任务切换——所有这些都由PostgreSQL+pgvector支持。

混合架构： PostgreSQL是本地工作引擎；GitHub是 长期的真理来源。导出、提交和推入一个命令。

______________________________________________________________________

目录

• 建筑
• 为什么选择KGN？
• 快速开始
• MCP服务器（克劳德集成）
• 多代理编排
• CLI命令
• 文件格式
• 发展
• 技术栈

______________________________________________________________________

建筑

要深入了解KGN的内部设计——层结构、模块依赖关系、数据库模式、数据流等——请参阅完整 架构指南 16张交互式美人鱼图。

graph LR
    A[".kgn / .kge"] --> B["Parser"]
    B --> C["IngestService"]
    C --> D[("PostgreSQL
+ pgvector")]
    D --> E["CLI · MCP · LSP · Web"]
    E --> F["Git / GitHub Sync"]

______________________________________________________________________

为什么选择KGN？

人工智能代理功能强大，但它们在会话之间会忘记一切——当多个代理协作时，它们可能会发生冲突、重复工作或失去对决策的跟踪。

KGN给你的特工一个 共享、可查询内存:

______________________________________________________________________

快速开始

📖 刚到KGN？ 按照以下步骤操作 入门指南 ( 韩语 )--不需要以前的经验。

安装

pip install kgn-mcp

启动数据库

git clone https://github.com/baobab00/kgn.git && cd kgn
docker compose -f docker/docker-compose.yml up -d postgres

首次运行

kgn init --project my-project
kgn ingest examples/ --project my-project --recursive
kgn status --project my-project

Embedding Provider Setup

若要使用嵌入功能，请在 .env 文件：

# .env
KGN_OPENAI_API_KEY=sk-your-api-key-here
KGN_OPENAI_EMBED_MODEL=text-embedding-3-small    # default

如果未设置API密钥，则摄取工作正常，嵌入将被静默跳过（优雅的降级）。

# Test provider connection
kgn embed provider test

Docker All-in-One

将PostgreSQL+kgn CLI与Docker一起运行：

docker compose -f docker/docker-compose.yml up -d --build
docker compose -f docker/docker-compose.yml exec kgn kgn init --project my-project
docker compose -f docker/docker-compose.yml exec kgn kgn --help

地方 .kgn/.kge 文件位于 docker/workspace/ 目录。

______________________________________________________________________

MCP服务器（克劳德集成）

MCP（模型上下文协议）服务器使Claude能够直接读取、写入和管理知识图中的任务。

# stdio mode (Claude Desktop / Claude Code default)
kgn mcp serve --project my-project

# HTTP SSE mode
KGN_MCP_TRANSPORT=sse KGN_MCP_PORT=8000 kgn mcp serve --project my-project

# streamable-http mode
KGN_MCP_TRANSPORT=streamable-http kgn mcp serve --project my-project

Claude桌面集成 --添加到 claude_desktop_config.json:

{
  "mcpServers": {
    "kgn": {
      "command": "uv",
      "args": ["run", "kgn", "mcp", "serve", "--project", "my-project"]
    }
  }
}

MCP Tools (12 tools)

Git/GitHub Sync

# Export DB → filesystem (+ auto-generate Mermaid README)
kgn sync export --project my-project --target ./sync

# Import filesystem → DB
kgn sync import --project my-project --source ./sync

# Push/pull to GitHub
kgn sync push --project my-project --target ./sync
kgn sync pull --project my-project --target ./sync

# Mermaid visualization
kgn graph mermaid --project my-project
kgn graph readme --project my-project --target ./sync

# Branch/PR management
kgn git branch list --target ./sync
kgn git pr create --project my-project --target ./sync --title "PR title"

Web Dashboard

pip install kgn-mcp[web]
kgn web serve --project my-project --port 8080

打开http://localhost:8080--图形视图、任务板、运行状况仪表板、搜索和筛选。

VS Code Extension

code --install-extension baobab00.vscode-kgn
pip install kgn-mcp[lsp]    # for LSP features

语法高亮显示、诊断、自动补全、悬停、转到定义、CodeLens、子图预览。

Error Code System

所有MCP错误响应均以结构化JSON返回：

{
  "error": "Error message",
  "code": "KGN-300",
  "detail": "Detailed description",
  "recoverable": false
}

多代理编排

KGN支持多代理协作工作流，其中多个AI代理在基于角色的访问控制、任务切换和冲突解决的知识图上协同工作。

• 5代理角色 --具有基于角色的访问控制的genesis、worker、reviewer、indexer、admin
• 3个工作流模板 --面向内建、问题解决、知识索引的设计
• 任务交接 --工作流步骤之间的自动上下文传播
• 咨询锁定 --防止对同一节点进行并发修改
• 冲突解决 --检测冲突并自动创建审阅任务
• 可观测性 --代理活动时间线、任务流统计数据、瓶颈检测

Agent Roles & Workflow Details

kgn agent list --project my-project
kgn agent role --project my-project --agent-id  --role worker
kgn agent stats --project my-project --agent-id 
kgn agent timeline --project my-project --agent-id 

CLI命令

跑 kgn --help 查看完整的命令列表。

关键命令摘要：

Expired Task Recovery

当已签出的任务超过其 lease_expires_at，它被认为 过期的. requeue_expired 重置已过期 IN_PROGRESS 任务到 READY 和增量 attempts.

• MCP： checkout 自动呼叫 requeue_expired 事先
• CLI： 需要手动调用或cron计划
• 当 max_attempts 超过（默认值3），任务将转换为 FAILED

文件格式

.kgn — Knowledge Graph Node

---
kgn_version: "0.1"
id: "new:my-node"        # UUID or new:slug
type: SPEC               # GOAL, ARCH, SPEC, LOGIC, DECISION, ISSUE, TASK, CONSTRAINT, ASSUMPTION, SUMMARY
title: "Node title"
status: ACTIVE            # ACTIVE, DEPRECATED, SUPERSEDED, ARCHIVED
project_id: "my-project"
agent_id: "my-agent"
tags: ["tag1", "tag2"]
confidence: 0.9
---

## Context
...
## Content
...

.kge — Edge Definition

---
kgn_version: "0.1"
project_id: "my-project"
agent_id: "my-agent"
edges:
  - from: "new:node-a"
    to:   "new:node-b"
    type: DEPENDS_ON      # DEPENDS_ON, IMPLEMENTS, RESOLVES, SUPERSEDES, DERIVED_FROM, CONTRADICTS, CONSTRAINED_BY
    note: "Edge description"
---

看 examples/ 实用指南 .kgn 和 .kge 文件示例。

发展

# Lint
uv run ruff check .

# Format
uv run ruff format .

# Test
uv run pytest --tb=short -q

# Coverage
uv run pytest --cov=kgn --cov-report=term-missing

技术栈

许可证

麻省理工学院