kg - local knowledge graph for your AI assistants

Beta - APIs may still change and some bugs are still expected.

kg gives your AI assistant persistent, structured, editable project memory stored locally as a knowledge graph.

Instead of relying only on document chunk retrieval, you can keep architecture, decisions, incidents, rules, dependencies, and workflows in a graph that is readable, reviewable, and Git-friendly.

Use it when you want your assistant to understand an existing project across sessions — not start from zero every time.

Why use it

• Persistent memory — keep project knowledge between conversations
• Structured, not fuzzy — inspect nodes, edges, facts, and gaps directly
• Editable and reviewable — store graphs as *.kg files with readable diffs
• Local-first — your project memory stays on your machine in git-friendly format
• Works with MCP clients — connect it as a local stdio MCP server

Why not just RAG

Classic RAG is good for retrieving text chunks from documents.

kg-mcp is better when you want:

• stable project memory instead of repeated retrieval
• explicit facts, relations, and dependencies
• graph updates during real work with the assistant
• something you can inspect, version, diff, and improve over time

Installation

Recommended install:

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

You can also download a ready binary from GitHub Releases.

Connect kg-mcp to Your AI Client

Add kg-mcp as a local stdio MCP server.

Example config:

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

After that:

1. restart your AI client,
2. confirm the kg MCP server is available,
3. start using the prompts below.

Full MCP setup and reference: docs/mcp.md

Generate a Graph

This is the first workflow for a new project: ask the assistant to create or extend a graph from your documentation.

By default, graphs are stored in ~/.kg/graphs as *.kg files.

Minimal prompt:

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.

Example prompt with documents:

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.

Longer prompt for this workflow: docs/ai-prompt-graph-from-docs.md

Ask the Assistant About Facts in the Graph

Once the graph exists, the normal workflow is to ask the assistant to inspect it and answer questions from it.

Example prompt:

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.

Other useful questions:

• "What rules control retries in the `payme

... View full README on GitHub