kgn

English | 한국어

<picture> <source media="(prefers-color-scheme: dark)" srcset="assets/kgn-banner-dark.png"> <source media="(prefers-color-scheme: light)" srcset="assets/kgn-banner-light.png"> <img alt="KGN — Knowledge Graph Node" src="assets/kgn-banner-light.png" width="100%"> </picture>

Manage your AI agent's knowledge — parse, store, query, and collaborate.

KGN is a developer-friendly CLI + MCP server for teams building with AI agents. Write knowledge nodes in simple YAML+Markdown files (.kgn), define relationships between them (.kge), and let KGN handle storage, similarity search, conflict detection, and multi-agent task handoffs — all backed by PostgreSQL + pgvector.

Hybrid architecture: PostgreSQL is the local working engine; GitHub is the long-term source of truth. Export, commit, and push in one command.

Table of Contents

• Architecture
• Why KGN?
• Quick Start
• MCP Server (Claude Integration)
• Multi-Agent Orchestration
• CLI Commands
• File Formats
• Development
• Tech Stack

Architecture

For a deep dive into KGN's internal design — layer structure, module dependencies, database schema, data flows, and more — see the full [Architecture Guide](ARCHITECTURE.md) with 16 interactive Mermaid diagrams.

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

Why KGN?

AI agents are powerful, but they forget everything between sessions — and when multiple agents collaborate, they can conflict, duplicate work, or lose track of decisions.

KGN gives your agents a shared, queryable memory:

Quick Start

📖 New to KGN? Follow the step-by-step [Getting Started Guide](GUIDE.md) ( 한국어 ) — no prior experience required.

Install

pip install kgn-mcp

Start Database

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

First Run

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

<details> <summary><b>Embedding Provider Setup</b></summary>

To use embedding features, set your OpenAI API key in the .env file:

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

If the API key is not set, ingest works normally and embedding is silently skipped (graceful degradation).

# Test provider connection
kgn embed provider test

</details>

<details> <summary><b>Docker All-in-One</b></summary>

Run PostgreSQL + kgn CLI together with 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

Place .kgn/.kge files in docker/workspace/ directory.

</details>

MCP Server (Claude Integration)

The MCP (Model Context Protocol) server enables Claude to directly read, write, and manage tasks in the knowledge graph.

# 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 Desktop integration — add to claude_desktop_config.json:

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

<details> <summary><b>MCP Tools (12 tools)</b></summary>

</details>

<details> <summary><b>Git/GitHub Sync</b></summary>

# 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"

</details>

<details> <summary><b>Web Dashboard</b></summary>

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

Open http://localhost:8080 — Graph View, Task Board, Health Dashboard, Search & Filter.

</details>

<details> <summary><b>VS Code Extension</b></summary>

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

Syntax Highlighting, Diagnostics, Auto-completion, Hover, Go to Definition, CodeLens, Subgraph Preview.

</details>

<details> <summary><b>Error Code System</b></summary>

All MCP error responses are returned as structured JSON:

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

</details>

Multi-Agent Orchestration

KGN supports multi-agent collaborative workflows where multiple AI agents work together on a knowledge graph with role-based access control, task handoff, and conflict resolution.

• 5 Agent Roles — genesis, worker, reviewer, indexer, admin with role-based access control
• 3 Workflow Templates — design-to-impl, issue-resolution, knowledge-indexing
• Task Handoff — Automatic context propagation between workflow steps
• Advisory Locking — Prevents concurrent modifications to the same node
• Conflict Resolution — Detects conflicts and auto-creates review tasks
• Observability — Agent activity timeline, task flow stats, bottleneck detection

<details> <summary><b>Agent Roles & Workflow Details</b></summary>

kgn agent list --project my-project
kgn agent role --project my-project --agent-id <uuid> --role worker
kgn agent stats --project my-project --agent-id <uuid>
kgn agent timeline --project my-project --agent-id <uuid>

</details>

CLI Commands

Run kgn --help for the full command list.

Key commands summary:

<details> <summary><b>Expired Task Recovery</b></summary>

When a checked-out task exceeds its lease_expires_at, it is considered expired. requeue_expired resets expired IN_PROGRESS tasks to READY and increments attempts.

• MCP: checkout automatically calls requeue_expired beforehand
• CLI: Manual invocation or cron schedule required
• When max_attempts (default 3) is exceeded, the task transitions to FAILED

</details>

File Formats

<details> <summary><b>.kgn — Knowledge Graph Node</b></summary>

---
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
...

</details>

<details> <summary><b>.kge — Edge Definition</b></summary>

---
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"
---

</details>

See examples/ directory for practical .kgn and .kge file examples.

Development

# 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

Tech Stack

License

MIT