Kairn

Контекстно-зависимый движок знаний для ИИ-ассистентов.

Статус: Alpha. API и CLI работают и протестированы (см. Разработка), но интерфейсы могут меняться между релизами. Отзывы и проблемы приветствуются.

Другие инструменты дают вашему ИИ память. Kairn даёт ему граф знаний с интеллектуальной маршрутизацией контекста. Он знает, что загружать, когда загружать и сколько — чтобы ваш ИИ оставался сфокусированным, а не перегруженным.

pip install kairn-ai
kairn init ~/brain
kairn serve ~/brain

Добавьте его в Claude Code одной строкой:

claude mcp add kairn -- kairn serve ~/brain

Или установите как пакет в один клик, без настройки Python: скачайте файл .mcpb из последнего релиза и откройте его в приложении, поддерживающем пакеты, например Claude Desktop.

Для других клиентов см. Быстрый старт ниже. Новичок в Kairn? Перейдите к Первым 5 минутам.

Способы установки

Пакет не содержит собственного исходного кода Kairn. Он объявляет kairn-ai как зависимость, и хост разрешает её с помощью uv, поэтому установка пакета и pip install выполняют один и тот же код. Место хранения базы данных настраивается при установке пакета; по умолчанию это ~/.kairn, и она никогда не покидает вашу машину.

Related MCP server: madb-mcp-server

Почему Kairn?

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

Kairn отличается:

• Контекстный маршрутизатор + прогрессивное раскрытие — автоматически загружает релевантные подграфы на основе ключевых слов, начиная с резюме и углубляясь в детали только при необходимости. Ни один другой инструмент этого не делает.

• Граф знаний с FTS5 — не плоское хранилище. Типизированные связи (depends-on, resolves, causes) между узлами с отслеживанием происхождения и полнотекстовым поиском по всему.

• Затухание опыта + автоматическое продвижение — опыт теряет актуальность со временем (биологическая модель затухания). Часто используемый опыт автоматически продвигается в постоянные знания. Ваш ИИ естественно забывает то, что не важно.

• 22 MCP-инструмента — работает с Claude Desktop, Cursor, VS Code, Windsurf и любым MCP-клиентом. Включает kn_judge для оценок связей с 5 глаголами и kn_doctor для диагностики здоровья только для чтения.

• Изоляция по рабочим областям — каждая рабочая область — это отдельное изолированное хранилище SQLite. JWT-аутентификация и управление доступом на основе ролей (владелец / сопровождающий / контрибьютор / читатель) входят в комплект для командных развертываний.

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

Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "kairn": {
      "command": "kairn",
      "args": ["serve", "~/brain"]
    }
  }
}

Cursor

Добавьте в .cursor/mcp.json:

{
  "mcpServers": {
    "kairn": {
      "command": "kairn",
      "args": ["serve", "~/brain"],
      "env": {
        "KAIRN_LOG_LEVEL": "WARNING"
      }
    }
  }
}

VS Code

Добавьте в .vscode/mcp.json:

{
  "servers": {
    "kairn": {
      "type": "stdio",
      "command": "kairn",
      "args": ["serve", "~/brain"]
    }
  }
}

Windsurf

Добавьте в ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "kairn": {
      "command": "kairn",
      "args": ["serve", "~/brain"]
    }
  }
}

Перезапустите редактор. 22 инструмента Kairn появятся в разделе MCP.

Первые 5 минут

Пошаговое руководство по первому запуску:

pip install kairn-ai
kairn init ~/brain              # creates the workspace + database

Добавьте однострочную команду из выше (или фрагмент быстрого старта для вашего клиента), затем перезапустите клиент. После подключения попросите ассистента запомнить что-то:

«Помни, что мы выбрали Postgres вместо SQLite для аналитического сервиса, потому что нам нужны были конкурентные писатели».

Это вызывает kn_learn под капотом и возвращает JSON-конверт, подобный этому (снято с реального запуска, через kairn learn, CLI-зеркало инструмента):

{"_v": "1.0", "stored_as": "node", "node_id": "002d9c22", "experience_id": "d0710c2f", "type": "decision", "confidence": "high", "namespace": "knowledge", "candidates": []}

Начните новую сессию и попросите вспомнить то же самое — это вызывает kn_recall и показывает то, что вы только что сохранили, без необходимости объяснять заново:

{"_v": "1.0", "count": 2, "results": [
  {"source": "node", "id": "002d9c22", "name": "Decision: we chose Postgres over SQLite for the analytics service beca", "type": "learned_decision", "description": "we chose Postgres over SQLite for the analytics service because we needed concurrent writers", "relevance": 1.0},
  {"source": "experience", "id": "d0710c2f", "type": "decision", "content": "we chose Postgres over SQLite for the analytics service because we needed concurrent writers", "confidence": "high", "relevance": 1.0}
]}

kn_learn сохранил и постоянный узел графа, и затухающий опыт (высокая уверенность делает и то, и другое, см. Маршрутизация по уверенности); kn_recall нашёл оба по теме из трёх слов.

Запустите kairn status ~/brain в любое время как смоук-тест — если он выводит JSON-блок статистики (количество узлов/рёбер/опытов), рабочая область здорова. Хотите скриптовый тур по всем основным функциям вместо ручного выполнения? Запустите kairn demo ~/brain — он проведёт вас через создание узлов, запросы, сохранение опыта, обучение, вспоминание и контекст примерно за 30 секунд.

Какой инструмент когда

22 инструмента — это много для запоминания в первый день. В большинстве сессий нужны только эти:

Всё остальное (kn_crossref, kn_related, kn_connect, kn_judge, kn_project/kn_projects/kn_log, kn_idea/kn_ideas, kn_promote_pending, kn_prune, kn_remove, kn_status, kn_doctor) — продвинутое использование — см. полный справочник 22 инструмента ниже, когда освоите основы.

22 инструмента (kn_ префикс)

Все инструменты следуют протоколу MCP с JSON-ответами.

Граф (6)

Память проекта (3)

Память опыта (5)

Идеи (2)

Интеллект (5)

Диагностика (1)

Ресурсы и подсказки

Ресурсы (контекст только для чтения для MCP-клиентов):

• kn://status — обзор графа, активный проект

• kn://projects — все проекты с недавним прогрессом

• kn://memories — недавние высокорелевантные переживания

Подсказки (управление сессией):

• kn_bootup — загрузить активный проект, недавний прогресс и главные воспоминания (начало сессии)

• kn_review — подвести итог сессии и предложить следующие шаги (конец сессии)

Как это работает

Архитектура

Any MCP Client (Claude, Cursor, VS Code)
        │
        ▼ MCP Protocol (stdio)
FastMCP Server (22 tools)
        │
   ┌────┼────┐
   ▼    ▼    ▼
Graph  Memory  Intelligence
Engine Engine  Layer
   │    │      │
   └────┼──────┘
        ▼
   SQLite + FTS5
   (per-workspace)

Модель затухания

Переживания теряют актуальность экспоненциально:

relevance(t) = initial_score × e^(-decay_rate × days)

Периоды полураспада откалиброваны по реальному хвосту доступа к производственному хранилищу переживаний, а не угаданы (одно исключение: preference — новый тип без истории доступа, поэтому его значение — задокументированная первоначальная оценка, пока не накопятся реальные данные).

Маршрутизация уверенности через kn_learn:

• high → постоянный узел + переживание (без затухания)

• medium → переживание с затуханием 2×

• low → переживание с затуханием 4×

• Автоповышение: 5+ обращений → постоянный узел

• Отслеживание обращений к узлам: kn_recall, kn_context и kn_crossref записывают, к каким узлам обращались, питая конвейер затухания и повышения

Бенчмарки

Kairn набирает 56,2% в целом по LongMemEval-S (оценено 500/500 вопросов, ридер и судья GPT-4o, один прогон, 0 ошибок). Это реальные цифры по каждой категории, включая плохие — каждая красная ячейка ведёт к её диагнозу:

500 вопросов включают 30 вариантов воздержания (правильный ответ — отказаться); они учтены внутри своих категорий выше и оцениваются отдельно: Kairn корректно воздерживается в 96,7% из них.

Задержка извлечения — ~1,4 мс на запрос (FTS5, в процессе, без сети). Протокол, заметки о честности и шаги воспроизведения: BENCHMARKS.md.

Эта таблица остаётся актуальной: каждый релиз, затрагивающий извлечение, переопубликовывает эти цифры, и слабая ячейка остаётся на доске, пока число действительно не изменится. Никаких выборочных прогонов, никаких скрытых категорий.

CLI

kairn init <path>              # Initialize workspace
kairn serve <path>             # Start MCP server (stdio)
kairn status <path>            # Graph stats
kairn demo <path>              # Interactive tutorial
kairn benchmark <path>         # Local performance benchmarks (latency, not LongMemEval)
kairn token-audit <path>       # Audit tool token usage
kairn import git <path> <repo>...  # Import git commit history (zero-LLM, offline)
kairn import claude-code <path>    # Import Claude Code session history (zero-LLM, offline)

Импорт вашей истории

kairn import git <workspace> <repo>... заполняет хранилище Kairn из одного или нескольких локальных git-репозиториев за $0 — без вызовов LLM, без сетевых вызовов. Префиксы обычных коммитов сопоставляются с типами переживаний (fix: -> solution, feat:/refactor:/perf: -> pattern, всё остальное -> decision); merge-коммиты пропускаются. Импортированные переживания попадают в отдельное пространство имён imported-git, отдельное от ваших органических знаний, поэтому их всегда можно отличить, а неудачный импорт полностью обратим.

kairn import git ~/brain ~/code/my-project --dry-run   # Preview first
kairn import git ~/brain ~/code/my-project              # Then import for real
kairn import git ~/brain ~/code/proj-a ~/code/proj-b --since 2026-01-01

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

Транскрипты Claude Code

kairn import claude-code <workspace> заполняет ваше хранилище Kairn из существующей истории сессий Claude Code, также за $0 и полностью офлайн. Если --root не указан, он сканирует ~/.claude/projects (и ~/.claude-secondary/projects, если у вас есть вторая учётная запись); --root PATH — повторяемое переопределение. Импортированные переживания попадают в собственное пространство имён imported-claude-code, поэтому они остаются отличными от ваших органических знаний, и неудачный импорт обратим.

kairn import claude-code ~/brain --dry-run              # Review exactly what would be stored
kairn import claude-code ~/brain                        # Import (prompts once before writing)
kairn import claude-code ~/brain --root ~/other/projects --since 2026-01-01 --yes

Что сохраняется (грубый режим): одно переживание на сессию — заголовок сессии плюс ваш первый запрос в этой сессии. Это намеренно краткое резюме с высокой точностью, а не детальное извлечение по каждому решению: экстрактор на основе правил без LLM не может надёжно отличить зафиксированное решение от обычного планирования, поэтому import claude-code импортирует чистый указатель уровня сессии вместо шумных фрагментов. Это не полный архив транскриптов и не разовая миграция — он идемпотентен и предназначен для повторного запуска по мере роста вашей истории.

Конфиденциальность. Каждая сохраняемая строка сначала пропускается через детерминированный редактор секретов (ключи API, заголовки Authorization/Bearer, присваивания password=/token=/secret=, типичные формы ключей вендоров, блоки приватных ключей, учётные данные, встроенные в URL). Выводы инструментов и блоки вызовов инструментов никогда не читаются, только ваш собственный текст запроса. Редактор — это защита в глубину, а не единственный контроль: реальный (не пробный) запуск ограничен явным подтверждением, а --dry-run показывает точный текст после редактирования до записи чего-либо. Редактирование ограничено набором правил, поэтому перед первым реальным импортом рекомендуется просмотр --dry-run; ничто никогда не покидает вашу машину.

Конфигурация

KAIRN_LOG_LEVEL=INFO|DEBUG|WARNING    # Default: WARNING
KAIRN_DB_PATH=~/brain/.kairn         # Default: {workspace}/.kairn
KAIRN_CACHE_SIZE=100                  # LRU cache entries
KAIRN_JWT_SECRET=<your-secret>        # Required for team features

Разработка

git clone https://github.com/primeline-ai/kairn
cd kairn
pip install -e ".[dev,team]"
pytest tests/ -v --cov
ruff check src/ && ruff format src/

Структура проекта

src/kairn/
├── server.py              # FastMCP server + 22 tools
├── cli.py                 # CLI commands
├── config.py              # Configuration
├── core/
│   ├── graph.py           # GraphEngine (6 tools)
│   ├── memory.py          # ProjectMemory (3 tools)
│   ├── experience.py      # ExperienceEngine (4 tools)
│   ├── ideas.py           # IdeaEngine (2 tools)
│   ├── intelligence.py    # IntelligenceLayer (5 tools)
│   └── router.py          # ContextRouter
├── storage/
│   ├── base.py            # Storage interface
│   └── sqlite_store.py    # SQLite + FTS5 implementation
├── models/                # Data models
├── events/                # Event bus
└── auth/                  # JWT + RBAC (team feature)

Производительность

Типичное время операций на современном оборудовании:

Используется в

Лицензия

MIT

Часть экосистемы PrimeLine

@PrimeLineAI · primeline.cc · Бесплатное руководство