kg

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

![CI](https://img.shields.io/github/actions/workflow/status/nnar1o/kg/ci.yml?branch=master)
![Release](https://img.shields.io/github/v/release/nnar1o/kg?display_name=tag&sort=semver)
![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)

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

```sh
cargo install kg-cli
```

### From script

Recommended install:

```sh
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:

```json
{
  "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`](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.

```text
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`](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:

```text
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:

```text
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`](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:

```sh
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:

```text
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:

```text
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:

```text
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:

```toml
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`:

```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:

```sh
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`](docs/mcp.md) - MCP setup and tool reference