kgn

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 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 ( 한국어 ) — 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

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

# Test provider connection
kgn embed provider test

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

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

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

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

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

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

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

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>

CLI Commands

Run kgn --help for the full command list.

Key commands summary:

File Formats

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

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

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