kg - local knowledge graph for your AI assistants

<img width="434" height="369" alt="image" src="https://github.com/user-attachments/assets/f53bf36f-ac6e-4f83-afaf-00ea9ef12b7e" />

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

From crates.io

cargo install kg-cli

From script

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

SCL quickstart

kg understands short, verb-first English commands (SCL — Simple Command Language). The active graph is resolved from your config automatically.

find "compressor defrost"
get concept:refrigerator
add concept:smart_fridge --name "Smart Fridge" --description "Connected refrigerator"
modify concept:smart_fridge --importance 0.9
remove concept:old_idea
connect process:compressor_control TRIGGERS process:auto_defrost
disconnect process:compressor_control TRIGGERS process:auto_defrost
list nodes
stats
use fridge
help

Core verbs

Verb	What it does
find <query>	search nodes by text
get <id>	fetch one node by id
add <id> --name "Name"	create a node (type inferred from id prefix)
modify <id> --field value	update node fields
remove <id>	delete a node
connect <src> <REL> <dst>	create an edge (alias: add edge)
disconnect <src> <REL> <dst>	delete an edge (alias: remove edge)
list nodes|edges|types|relations|graphs	list graph contents
stats	show graph statistics
use <graph>	switch active graph
help [verb]	get help for a verb or all
feedback <uid> yes|no|nil|pick <n>	give feedback on search results
strict	disable defaults for following lines

IDs

Format: <type>:snake_case — e.g. concept:fridge, bug:door_seal, process:compressor_cycle.

Relations

HAS USES STORED_IN TRIGGERS CREATED_BY AFFECTED_BY AVAILABLE_IN DOCUMENTED_IN DEPENDS_ON TRANSITIONS DECIDED_BY GOVERNED_BY READS_FROM

Tips

• Flags go after positional args. Quote multiword values.
• Separate commands with ; or newlines. Lines starting with # are comments.
• Use use <graph> to switch graphs within a script.
• Canonical kg <graph> node find ... commands still work as fallback.
• Full SCL reference: docs/scl.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

For a ready-made repository example, run cargo run --bin repo-example to generate repo-example.kg from this repo.

Automatic graph for a directory

kg can turn an existing folder into a graph automatically. It scans the directory tree, recognizes many common file types, extracts symbols for Rust, Java, JavaScript/TypeScript, Python, and C/C++, and keeps the generated structure separate from the manual graph.

For markdown-like documents, it also creates document (GDOC) and chapter (GSEC) nodes with section content.

It is a fast way to get a useful map of a codebase or workspace without modeling everything by hand. The generated index is local, refreshable, and safe to ignore in git.

Example:

cargo run --bin repo-example

This generates repo-example.kg from this repository as a local demo.

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 payments graph?"
• "Which systems write to the orders datastore?"
• "What is missing or weak in this graph?"
• "Which nodes and edges explain the authorization flow?"

Add or Update Facts Through the Assistant

You can also ask the assistant to improve the graph while you work.

Example prompt:

Use kg-mcp to review my existing `payments` graph.

Find:
- missing important nodes,
- weak descriptions,
- missing facts,
- suspicious or low-value edges.

Apply safe improvements where possible.
Only add facts grounded in the graph, the provided docs, or the current discussion.
If something is ambiguous, leave it out or add a note.

When you finish, summarize:
- what was wrong,
- what you changed,
- what still needs manual review.

This works best when your main system prompt or project prompt already tells the assistant which graph belongs to the project.

Minimal project-level prompt:

You are connected to kg-mcp.
Project graph name: payments.
Use this graph for relevant reads and updates in this project.
If you notice important missing information that is grounded in the available docs or conversation context, update the graph as part of your work.
If uncertain, ask or add a note instead of inventing facts.

Tips

Project config (.kg.toml)

kg looks for .kg.toml in the current directory and its parent directories.

Example:

backend = "json" # json backend writes native .kg files by default
graph_dir = ".kg/graphs"
graph_dirs = ["../shared-graphs", "../team-graphs"]
nudge = 20
user_short_uid = "dev_01"

[graphs]
payments = "graphs/payments.kg"

Notes:

• backend = "json" is the default and prefers .kg text graphs.
• backend = "redb" stores graphs in .db files.
• graph_dir sets a primary graph directory.
• graph_dirs adds extra directories scanned by kg list and graph resolution.

Keep Graphs in Git

The default graph directory is ~/.kg/graphs.

You can put that directory under git.

Recommended approach:

• keep the main *.kg graph files in git,
• ignore generated sidecars and local operational files,
• treat backup snapshots and event logs as local machine history unless you explicitly want to version them.

Suggested .gitignore:

*.kglog
*.kgindex
*.event.log
*.migration.log
*.bak
*.bck.*.gz

In practice:

• *.kg is the main graph file you usually want to review and commit,
• *.kglog is a local access/feedback log,
• *.kgindex is a generated local index,
• *.event.log is a local append-only change timeline,
• *.bak is the previous on-disk version from the last write,
• *.bck.*.gz are periodic compressed backup snapshots,
• *.migration.log is a migration report when older graphs are converted.

*.kg is git-friendly and intentionally structured to make diffs readable and merges easier when several people work on the same graph.

Export a Graph to HTML

To generate an interactive HTML view of a graph:

kg graph payments export-html --output payments.html

You can keep the generated HTML as a shareable visual snapshot of the current graph.

Documentation

• docs/mcp.md - MCP setup and tool reference
• docs/ai-prompt-graph-from-docs.md - longer prompt for document ingestion
• docs/build-graph-from-docs.md - graph-building workflow from docs
• docs/troubleshooting.md - common issues

Contact

For questions or feedback: nnar10@proton.me