kg — локальный граф знаний для ваших ИИ-ассистентов

Бета — API могут меняться, и возможны некоторые ошибки.

kg даёт вашему ИИ-ассистенту постоянную, структурированную, редактируемую память о проекте, хранящуюся локально в виде графа знаний.

Вместо того чтобы полагаться только на извлечение фрагментов документов, вы можете хранить архитектуру, решения, инциденты, правила, зависимости и рабочие процессы в графе, который удобно читать, просматривать и использовать с Git.

Используйте его, когда хотите, чтобы ассистент понимал существующий проект между сессиями, а не начинал с нуля каждый раз.

Зачем это использовать

• Постоянная память — храните знания о проекте между разговорами

• Структурированно, а не размыто — просматривайте узлы, рёбра, факты и пробелы напрямую

• Редактируемо и проверяемо — храните графы в файлах *.kg с читаемыми диффами

• Локально-ориентированный — память о проекте остаётся на вашей машине в формате, удобном для Git

• Работает с MCP-клиентами — подключайте его как локальный stdio MCP-сервер

Related MCP server: Agentic Memory Server

Почему не просто RAG

Классический RAG хорош для извлечения фрагментов текста из документов.

kg-mcp лучше, когда вы хотите:

• стабильную память о проекте вместо повторного извлечения

• явные факты, связи и зависимости

• обновление графа во время реальной работы с ассистентом

• то, что можно просматривать, версионировать, диффить и улучшать со временем

Установка

Из crates.io

cargo install kg-cli

Из скрипта

Рекомендуемая установка:

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

Вы также можете скачать готовый бинарник из GitHub Releases.

Подключение kg-mcp к вашему ИИ-клиенту

Добавьте kg-mcp как локальный stdio MCP-сервер.

Пример конфигурации:

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

После этого:

1. перезапустите ваш ИИ-клиент,

2. убедитесь, что MCP-сервер kg доступен,

3. начните использовать приведённые ниже подсказки.

Полная настройка MCP и справочник: docs/mcp.md

Быстрый старт SCL

kg понимает короткие английские команды, начинающиеся с глагола (SCL — Simple Command Language). Активный граф определяется из вашей конфигурации автоматически.

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

Основные глаголы

ID

Формат: <type>:snake_case — например, concept:fridge, bug:door_seal, process:compressor_cycle.

Связи

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

Советы

• Флаги идут после позиционных аргументов. Значения из нескольких слов заключайте в кавычки.

• Разделяйте команды символом ; или переводами строк. Строки, начинающиеся с #, являются комментариями.

• Используйте use <graph> для переключения графов внутри скрипта.

• Канонические команды kg <graph> node find ... по-прежнему работают как запасной вариант.

• Полный справочник SCL: docs/scl.md

Создание графа

Это первый рабочий процесс для нового проекта: попросите ассистента создать или расширить граф на основе вашей документации.

По умолчанию графы хранятся в ~/.kg/graphs в виде файлов *.kg.

Минимальный запрос:

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.

Пример запроса с документами:

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.

Более длинный запрос для этого рабочего процесса: docs/ai-prompt-graph-from-docs.md

Для готового примера репозитория выполните cargo run --bin repo-example, чтобы сгенерировать repo-example.kg из этого репозитория.

Автоматический граф для каталога

kg может автоматически превратить существующую папку в граф. Он сканирует дерево каталогов, распознаёт многие распространённые типы файлов, извлекает символы для Rust, Java, JavaScript/TypeScript, Python и C/C++ и хранит сгенерированную структуру отдельно от ручного графа.

Для документов, похожих на Markdown, он также создаёт узлы документа (GDOC) и главы (GSEC) с содержимым разделов.

Это быстрый способ получить полезную карту кодовой базы или рабочего пространства, не моделируя всё вручную. Сгенерированный индекс является локальным, обновляемым и его можно безопасно игнорировать в git.

Пример:

cargo run --bin repo-example

Это генерирует repo-example.kg из этого репозитория в качестве локальной демонстрации.

Спросите ассистента о фактах в графе

Когда граф существует, обычный рабочий процесс — попросить ассистента изучить его и ответить на вопросы на его основе.

Пример запроса:

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.

Другие полезные вопросы:

• «Какие правила управляют повторами в графе payments?»

• «Какие системы пишут в хранилище данных заказов?»

• «Чего не хватает или что слабо в этом графе?»

• «Какие узлы и рёбра объясняют поток авторизации?»

Добавление или обновление фактов через ассистента

Вы также можете попросить ассистента улучшить граф во время работы.

Пример запроса:

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.

Это лучше всего работает, когда ваш основной системный запрос или запрос проекта уже сообщает ассистенту, какой граф принадлежит проекту.

Минимальный запрос на уровне проекта:

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.

Советы

Конфигурация проекта (.kg.toml)

kg ищет .kg.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"

Примечания:

• backend = "json" используется по умолчанию и предпочитает текстовые графы .kg.

• backend = "redb" хранит графы в файлах .db.

• graph_dir задаёт основной каталог графов.

• graph_dirs добавляет дополнительные каталоги, сканируемые kg list и при разрешении графов.

Хранение графов в Git

Каталог графов по умолчанию — ~/.kg/graphs.

Вы можете поместить этот каталог под управление git.

Рекомендуемый подход:

• храните основные файлы графов *.kg в git,

• игнорируйте сгенерированные вспомогательные файлы и локальные операционные файлы,

• относитесь к резервным снимкам и журналам событий как к локальной истории машины, если вы явно не хотите их версионировать.

Предлагаемый .gitignore:

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

На практике:

• *.kg — это основной файл графа, который вы обычно хотите просматривать и коммитить,

• *.kglog — локальный журнал доступа/обратной связи,

• *.kgindex — сгенерированный локальный индекс,

• *.event.log — локальная временная шкала изменений с добавлением только в конец,

• *.bak — предыдущая версия на диске от последней записи,

• *.bck.*.gz — периодические сжатые резервные снимки,

• *.migration.log — отчёт о миграции при преобразовании старых графов.

*.kg удобен для git и специально структурирован так, чтобы диффы были читаемыми, а слияния — проще, когда несколько человек работают над одним графом.

Экспорт графа в HTML

Чтобы сгенерировать интерактивное HTML-представление графа:

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

Вы можете сохранить сгенерированный HTML как доступный для общего доступа визуальный снимок текущего графа.

Документация

• docs/mcp.md — настройка MCP и справочник инструментов

• docs/ai-prompt-graph-from-docs.md — более длинный запрос для приёма документов

• docs/build-graph-from-docs.md — рабочий процесс построения графа из документов

• docs/troubleshooting.md — распространённые проблемы

Контакты

По вопросам или обратной связи: nnar10@proton.me