{
  "markdown": "# kg - local knowledge graph for your AI assistants\n\n<img width=\"434\" height=\"369\" alt=\"image\" src=\"https://github.com/user-attachments/assets/f53bf36f-ac6e-4f83-afaf-00ea9ef12b7e\" />\n\n![CI](https://img.shields.io/github/actions/workflow/status/nnar1o/kg/ci.yml?branch=master)\n![Release](https://img.shields.io/github/v/release/nnar1o/kg?display_name=tag&sort=semver)\n![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)\n\n> **Beta** - APIs may still change and some bugs are still expected.\n\n\n`kg` gives your AI assistant persistent, structured, editable project memory stored locally as a knowledge graph.\n\nInstead 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.\n\nUse it when you want your assistant to understand an existing project across sessions — not start from zero every time.\n\n## Why use it\n\n- **Persistent memory** — keep project knowledge between conversations\n- **Structured, not fuzzy** — inspect nodes, edges, facts, and gaps directly\n- **Editable and reviewable** — store graphs as `*.kg` files with readable diffs\n- **Local-first** — your project memory stays on your machine in git-friendly format\n- **Works with MCP clients** — connect it as a local stdio MCP server\n\n## Why not just RAG\n\nClassic RAG is good for retrieving text chunks from documents.\n\n`kg-mcp` is better when you want:\n- stable project memory instead of repeated retrieval\n- explicit facts, relations, and dependencies\n- graph updates during real work with the assistant\n- something you can inspect, version, diff, and improve over time\n\n## Installation\n\n### From crates.io\n\n```sh\ncargo install kg-cli\n```\n\n### From script\n\nRecommended install:\n\n```sh\ncurl -sSL https://raw.githubusercontent.com/nnar1o/kg/master/install.sh | sh\n```\n\nYou can also download a ready binary from GitHub Releases.\n\n## Connect `kg-mcp` to Your AI Client\n\nAdd `kg-mcp` as a local stdio MCP server.\n\nExample config:\n\n```json\n{\n  \"mcpServers\": {\n    \"kg\": {\n      \"command\": \"/absolute/path/to/kg-mcp\"\n    }\n  }\n}\n```\n\nAfter that:\n\n1. restart your AI client,\n2. confirm the `kg` MCP server is available,\n3. start using the prompts below.\n\nFull MCP setup and reference: [`docs/mcp.md`](docs/mcp.md)\n\n## SCL quickstart\n\n`kg` understands short, verb-first English commands (SCL — Simple Command Language).\nThe active graph is resolved from your config automatically.\n\n```text\nfind \"compressor defrost\"\nget concept:refrigerator\nadd concept:smart_fridge --name \"Smart Fridge\" --description \"Connected refrigerator\"\nmodify concept:smart_fridge --importance 0.9\nremove concept:old_idea\nconnect process:compressor_control TRIGGERS process:auto_defrost\ndisconnect process:compressor_control TRIGGERS process:auto_defrost\nlist nodes\nstats\nuse fridge\nhelp\n```\n\n### Core verbs\n\n| Verb | What it does |\n|------|-------------|\n| `find <query>` | search nodes by text |\n| `get <id>` | fetch one node by id |\n| `add <id> --name \"Name\"` | create a node (type inferred from id prefix) |\n| `modify <id> --field value` | update node fields |\n| `remove <id>` | delete a node |\n| `connect <src> <REL> <dst>` | create an edge (alias: `add edge`) |\n| `disconnect <src> <REL> <dst>` | delete an edge (alias: `remove edge`) |\n| `list nodes\\|edges\\|types\\|relations\\|graphs` | list graph contents |\n| `stats` | show graph statistics |\n| `use <graph>` | switch active graph |\n| `help [verb]` | get help for a verb or all |\n| `feedback <uid> yes\\|no\\|nil\\|pick <n>` | give feedback on search results |\n| `strict` | disable defaults for following lines |\n\n### IDs\n\nFormat: `<type>:snake_case` — e.g. `concept:fridge`, `bug:door_seal`, `process:compressor_cycle`.\n\n### Relations\n\n`HAS USES STORED_IN TRIGGERS CREATED_BY AFFECTED_BY AVAILABLE_IN DOCUMENTED_IN DEPENDS_ON TRANSITIONS DECIDED_BY GOVERNED_BY READS_FROM`\n\n### Tips\n\n- Flags go after positional args. Quote multiword values.\n- Separate commands with `;` or newlines. Lines starting with `#` are comments.\n- Use `use <graph>` to switch graphs within a script.\n- Canonical `kg <graph> node find ...` commands still work as fallback.\n- Full SCL reference: [`docs/scl.md`](docs/scl.md)\n\n## Generate a Graph\n\nThis is the first workflow for a new project: ask the assistant to create or extend a graph from your documentation.\n\nBy default, graphs are stored in `~/.kg/graphs` as `*.kg` files.\n\nMinimal prompt:\n\n```text\nYou are connected to kg-mcp.\n\nProject graph name: payments\n\nBuild or extend this graph from the project documentation I provide.\nUse `payments` as the graph name for all graph operations.\n\nOnly add facts grounded in source material.\nIf an important fact is missing and can be inferred safely from the provided docs, update the graph.\nIf something is ambiguous, ask or record it as a note instead of inventing facts.\n```\n\nExample prompt with documents:\n\n```text\nUse kg-mcp to build or extend the `payments` graph from these documents:\n- docs/payments/overview.md\n- docs/payments/retries.md\n- docs/payments/providers.md\n\nOnly add facts grounded in the documents.\nIf something is ambiguous, keep it out of the graph or record it as a note.\nWhen you finish, summarize what was added, what remains unclear, and what document should be ingested next.\n```\n\nLonger prompt for this workflow: [`docs/ai-prompt-graph-from-docs.md`](docs/ai-prompt-graph-from-docs.md)\n\nFor a ready-made repository example, run `cargo run --bin repo-example` to generate `repo-example.kg` from this repo.\n\n### Automatic graph for a directory\n\n`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.\n\nFor markdown-like documents, it also creates document (`GDOC`) and chapter (`GSEC`) nodes with section content.\n\nIt 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.\n\nExample:\n\n```sh\ncargo run --bin repo-example\n```\n\nThis generates `repo-example.kg` from this repository as a local demo.\n\n## Ask the Assistant About Facts in the Graph\n\nOnce the graph exists, the normal workflow is to ask the assistant to inspect it and answer questions from it.\n\nExample prompt:\n\n```text\nUse kg-mcp to inspect my existing `payments` graph.\n\nI want to understand:\n- how payment authorization works,\n- what triggers retries,\n- which external providers are involved,\n- which datastore reads and writes are part of the flow.\n\nIf the graph is missing critical information, say exactly what is missing.\n```\n\nOther useful questions:\n\n- \"What rules control retries in the `payments` graph?\"\n- \"Which systems write to the orders datastore?\"\n- \"What is missing or weak in this graph?\"\n- \"Which nodes and edges explain the authorization flow?\"\n\n## Add or Update Facts Through the Assistant\n\nYou can also ask the assistant to improve the graph while you work.\n\nExample prompt:\n\n```text\nUse kg-mcp to review my existing `payments` graph.\n\nFind:\n- missing important nodes,\n- weak descriptions,\n- missing facts,\n- suspicious or low-value edges.\n\nApply safe improvements where possible.\nOnly add facts grounded in the graph, the provided docs, or the current discussion.\nIf something is ambiguous, leave it out or add a note.\n\nWhen you finish, summarize:\n- what was wrong,\n- what you changed,\n- what still needs manual review.\n```\n\nThis works best when your main system prompt or project prompt already tells the assistant which graph belongs to the project.\n\nMinimal project-level prompt:\n\n```text\nYou are connected to kg-mcp.\nProject graph name: payments.\nUse this graph for relevant reads and updates in this project.\nIf you notice important missing information that is grounded in the available docs or conversation context, update the graph as part of your work.\nIf uncertain, ask or add a note instead of inventing facts.\n```\n\n## Tips\n\n### Project config (`.kg.toml`)\n\n`kg` looks for `.kg.toml` in the current directory and its parent directories.\n\nExample:\n\n```toml\nbackend = \"json\" # json backend writes native .kg files by default\ngraph_dir = \".kg/graphs\"\ngraph_dirs = [\"../shared-graphs\", \"../team-graphs\"]\nnudge = 20\nuser_short_uid = \"dev_01\"\n\n[graphs]\npayments = \"graphs/payments.kg\"\n```\n\nNotes:\n\n- `backend = \"json\"` is the default and prefers `.kg` text graphs.\n- `backend = \"redb\"` stores graphs in `.db` files.\n- `graph_dir` sets a primary graph directory.\n- `graph_dirs` adds extra directories scanned by `kg list` and graph resolution.\n\n### Keep Graphs in Git\n\nThe default graph directory is `~/.kg/graphs`.\n\nYou can put that directory under git.\n\nRecommended approach:\n\n- keep the main `*.kg` graph files in git,\n- ignore generated sidecars and local operational files,\n- treat backup snapshots and event logs as local machine history unless you explicitly want to version them.\n\nSuggested `.gitignore`:\n\n```gitignore\n*.kglog\n*.kgindex\n*.event.log\n*.migration.log\n*.bak\n*.bck.*.gz\n```\n\nIn practice:\n\n- `*.kg` is the main graph file you usually want to review and commit,\n- `*.kglog` is a local access/feedback log,\n- `*.kgindex` is a generated local index,\n- `*.event.log` is a local append-only change timeline,\n- `*.bak` is the previous on-disk version from the last write,\n- `*.bck.*.gz` are periodic compressed backup snapshots,\n- `*.migration.log` is a migration report when older graphs are converted.\n\n`*.kg` is git-friendly and intentionally structured to make diffs readable and merges easier when several people work on the same graph.\n\n### Export a Graph to HTML\n\nTo generate an interactive HTML view of a graph:\n\n```sh\nkg graph payments export-html --output payments.html\n```\n\nYou can keep the generated HTML as a shareable visual snapshot of the current graph.\n\n## Documentation\n\n- [`docs/mcp.md`](docs/mcp.md) - MCP setup and tool reference\n- [`docs/ai-prompt-graph-from-docs.md`](docs/ai-prompt-graph-from-docs.md) - longer prompt for document ingestion\n- [`docs/build-graph-from-docs.md`](docs/build-graph-from-docs.md) - graph-building workflow from docs\n- [`docs/troubleshooting.md`](docs/troubleshooting.md) - common issues\n\n## Contact\n\nFor questions or feedback: `nnar10@proton.me`\n",
  "bytes": 10348,
  "sha": "a834812c353e34c9325fb6fa09d9d7997708b8426e5b6072c03a0e2129b0e9d8",
  "repo_slug": "nnar1o/kg",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_nnar1o_kg_mcp_2dd54e95/readme"
}