agent-knowledge

Кросс-сессионная память и поиск для ИИ-ассистентов программирования — работает с Claude Code, Cursor, OpenCode, Cline, Continue.dev и Aider из коробки. Git-синхронизируемая база знаний, гибридный семантический + TF-IDF поиск, автоматическая дистилляция с очисткой секретов.

Бенчмарк: R@5 = 97.2% (разреженный) / 98.8% (гибридный) на longmemeval_s и 86.0% (разреженный) / 88.4% (гибридный) на более сложном разбиении longmemeval_m — публичный академический бенчмарк LongMemEval (Wu et al. 2024, ICLR 2025), полные 500 вопросов на каждое разбиение, без LLM, без API-ключа, полностью офлайн. +8.6pp до +13.2pp R@5 по сравнению с официальным базовым flat-bm25 из статьи при воспроизведении один в один. Полная таблица по категориям, инструкции по воспроизведению и детали сравнения с статьей — в bench/README.md.

Зачем

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

agent-knowledge решает эту проблему с помощью двух взаимодополняющих систем:

1. База знаний — git-синхронизируемое хранилище markdown со структурированными записями (решения, рабочие процессы, контекст проекта), которое сохраняется между сессиями и машинами.

2. Поиск по сессиям — TF-IDF ранжированный полнотекстовый поиск по транскриптам сессий из всех ваших инструментов программирования, чтобы агенты могли вспомнить, что происходило раньше — независимо от того, какой инструмент использовался.

Related MCP server: Doclea MCP

Поддерживаемые инструменты

Сессии всех основных ИИ-ассистентов программирования обнаруживаются автоматически — если инструмент установлен, его сессии появляются автоматически.

Никакой настройки не требуется. Дополнительные корни сессий можно добавить через переменную окружения AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS (пути через запятую).

Возможности

• Независимый от хоста поиск по сессиям — унифицированный поиск по всем основным ИИ-ассистентам программирования (Claude Code, Cursor, Codex CLI, Aider, Continue.dev, Cline, OpenCode). Никакое имя хоста не зашито в конфигурацию — реестр адаптеров зондирует установленные корни хостов при запуске.

• Гибридный поиск — семантическое векторное сходство, смешанное с TF-IDF ранжированием по ключевым словам.

• Git-синхронизируемая база знаний — markdown-хранилище с YAML frontmatter, автоматический коммит и push при записи.

• Автоматическое обнаружение устаревания — knowledge_analyze(action: "stale_by_code_activity") перекрёстно сверяет пути файлов, упомянутые в теле каждой записи, с filesModified в недавних сводках сессий. В паре с уровнем точности по наличию символов: идентификаторы, которые цитирует запись (инлайн-бэктики + блоки в кавычках), проверяются в затронутом файле; если они всё ещё существуют, уверенность понижается на ×0.3. Записи с evergreen: true освобождаются.

• Отслеживание пробелов в поиске — knowledge_analyze(action: "search_gaps") выявляет запросы с нулевыми результатами за последние since_days, сгруппированные по токенному сходству Жаккара. Самый ясный сигнал для «какие записи мне написать следующими?».

• Упаковщик контекста с приоритетом секций — knowledge(action: "wakeup") собирает многосекционный пакет (identity → active_tasks → recent_decisions → known_gotchas → last_session_summary → top_weighted → semantic_fallback) в рамках токенного бюджета (по умолчанию 800, переопределяется через token_budget или AGENT_KNOWLEDGE_WAKEUP_BUDGET). Неиспользованный бюджет секции перераспределяется на последующие секции.

• Оценённый и ограниченный промоутер — инсайты сессий продвигаются через взвешенный скорер с 6 сигналами и тремя независимыми порогами (minScore, minRecallCount, minUniqueQueries). Работает автоматически в фоне, по запросу через knowledge_admin(action: "promote") или проверяем офлайн через npm run bench:promote. Каждый запуск создаёт аудируемый дневник .dreams/YYYY-MM-DD.md.

• Подключаемая система адаптеров — добавьте поддержку новых инструментов, реализовав интерфейс SessionAdapter.

• Эмбеддинги — локальные (Hugging Face), OpenAI, Claude/Voyage или Gemini провайдеры.

• Нечёткое сопоставление — поиск, устойчивый к опечаткам, с использованием расстояния Левенштейна.

• 6 областей поиска — ошибки, планы, конфигурации, инструменты, файлы, решения.

• 6 MCP-инструментов — консолидированный интерфейс на основе действий (knowledge, knowledge_search, knowledge_session, knowledge_graph, knowledge_analyze, knowledge_admin).

• Вечнозелёные записи — evergreen: true в frontmatter освобождает запись от затухания в ранжировании И делает её только добавляемой при продвижении. Дашборд отображает значок-булавку на таких карточках.

• Авторство — необязательный author: <string> в frontmatter отображается как приглушённый чип на каждой карточке.

• Разрешение графа кода — типы рёбер calls, imports, inherits для структуры кода; направленный BFS-обход (outbound/inbound/both); bulk_link для эффективного приёма; unlink_by_origin для очистки устаревших рёбер кода перед повторным приёмом; идентификаторы узлов с префиксом code: отличают код от знаний.

• Временной граф знаний — рёбра поддерживают окна валидности valid_from / valid_to; запросы as_of возвращают снимки на момент времени; действие invalidate помечает факты как завершённые без их удаления.

• Гибридные бусты скоринга — бусты для имён собственных и временной близости поверх TF-IDF + семантического смешивания, ограниченные +66.7%, с коротким замыканием, когда сигналы отсутствуют.

• Категория как буст (а не фильтр) — включите category_mode: "boost", чтобы неверное предположение категории понижало ранг вместо отбрасывания правильного ответа.

• Дословное индексирование сессий — чанки по сообщениям (≥30 символов) встраиваются в векторное хранилище, чтобы необработанный разговор был доступен для поиска; переключается через AGENT_KNOWLEDGE_INDEX_VERBATIM=false.

• Настраиваемый git URL — knowledge_admin(action: "config") для настройки во время выполнения, сохраняется в XDG/AppData.

• Кросс-машинная персистентность — знания синхронизируются через git, сессии читаются из локального хранилища каждого инструмента.

• Дашборд в реальном времени — просмотр, поиск и управление на localhost:3423.

• Очистка секретов — API-ключи, токены, пароли, приватные ключи автоматически редактируются перед git push.

• Граф знаний — рёбра связей между записями (related_to, supersedes, depends_on, contradicts, specializes, part_of, alternative_to, builds_on) с BFS-обходом.

• Оценка уверенности/затухания — записи оцениваются по частоте и давности доступа; автоматическое продвижение от кандидата к установленному и проверенному.

• Консолидация памяти — TF-IDF обнаружение дубликатов при записи (предупреждает о похожих записях) плюс knowledge_analyze(action: "consolidate") для пакетного сканирования дубликатов.

• Цикл рефлексии — knowledge_analyze(action: "reflect") выявляет несвязанные записи и генерирует структурированные подсказки для агента по выявлению новых связей в графе.

• Автосвязывание при записи — новые записи автоматически связываются с топ-3 похожими существующими записями, когда косинусное сходство > 0.7.

• Метаданные уверенности — записи помечаются как extracted (написаны пользователем) или inferred (авто-дистиллированные, множитель ранга поиска 0.85×); поле confidence_score несёт уверенность модели от 0 до 1.

• Анализ знаний — действия knowledge_analyze: god_nodes (наиболее связанные записи), bridges (кросс-категорийные соединители), gaps (изолированные записи).

• Краткая сводка знаний — knowledge_analyze(action: "brief") возвращает кэшированное резюме ~200 токенов (основные концепции, активные проекты, недавние решения, количество устаревших и пробелов) для ориентации в начале сессии.

• Происхождение рёбер — рёбра графа отслеживают origin (manual, auto-link, distill, reflect), чтобы анализ мог отличать пользовательские суждения от автоматических эвристик.

• Детерминированная предварительная экстракция в дистилляции — сводки сессий теперь включают git-коммиты, паттерны ошибок, посещённые URL и изменённые пакеты, извлечённые через regex из вывода bash/инструментов (без затрат на LLM).

• Метаданные свежести на каждом результате поиска — каждый результат знаний несёт freshness: { body_age_days, last_accessed, access_count, verified_at, verification_age_days, evergreen }. Агент читает сигнал доверия и решает; мы не навязываем политику понижения.

• Окна затухания по категориям — фильтр «Неиспользуемые» и диаграмма по типам учитывают пороги по категориям (проекты 180д, люди 365д, решения 90д, рабочие процессы 60д, заметки 30д), чтобы контент, связанный с идентичностью, не выглядел устаревшим только потому, что его не перечитывают еженедельно.

• Хуки жизненного цикла — SessionStart авто-пробуждение + проверка свежести приёма, UserPromptSubmit целевая инъекция первого промпта, PreCompact напоминание о сбросе памяти + дистилляция, SessionEnd дистилляция. Всего шесть скриптов хуков, все с отказоустойчивостью, каждый переключается через переменную окружения AGENT_KNOWLEDGE_*. См. docs/HOOKS.md.

• Заменяет авто-память хоста — на хостах с системой памяти на сессию (память Claude Code ~/.claude/projects/*/memory/, аналогично в других IDE), направляйте долговременные факты пользователя и обратную связь в agent-knowledge вместо этого. Авто-память локальна для машины и невидима для других машин; agent-knowledge синхронизируется через git, кросс-машинна, доступна для поиска и появляется при пробуждении. См. примечание об интеграции с Claude Code в docs/USER-MANUAL.md.

Приём кодовой базы

Навык knowledge-ingest заполняет или обновляет базу знаний из директории кодовой базы. Он использует tree-sitter для структурной экстракции без токенов (классы, функции, импорты, графы вызовов, комментарии с обоснованием), затем кластеризует файлы в подсистемы и создаёт записи знаний + рёбра графа через существующие MCP-инструменты. Последующие запуски инкрементальны — обрабатываются только изменённые файлы.

/knowledge-ingest ./my-project

Использует стандарт Agent Skills — работает с Claude Code, OpenCode, Cursor, Codex CLI и Gemini CLI. Подробности см. в Руководстве по приёму.

Поддерживаемые языки: TypeScript, JavaScript, Python, Go, Rust, Java, C, C++.

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

Установка из npm

npm install -g agent-knowledge

Или клонирование из исходников

git clone https://github.com/keshrath/agent-knowledge.git
cd agent-knowledge
npm install && npm run build

Вариант 1: MCP-сервер (для ИИ-агентов)

Добавьте в конфиг вашего MCP-клиента (Claude Code, Cline и т.д.):

{
  "mcpServers": {
    "agent-knowledge": {
      "command": "npx",
      "args": ["agent-knowledge"]
    }
  }
}

Дашборд автоматически запускается на http://localhost:3423 при первом MCP-подключении.

См. Руководство по настройке для инструкций по конкретным клиентам (Claude Code, Cursor, Windsurf, OpenCode).

Вариант 2: Автономный сервер (для REST/WebSocket клиентов)

node dist/server.js --port 3423

MCP-инструменты (6)

База знаний

Поиск

Форма ответа: {mode: "general" | "scoped", sessions, knowledge}. В ограниченном режиме knowledge: [] по замыслу.

Области (scopes): errors, plans, configs, tools, files, decisions, all.

Параметры поиска:

• mmr: true — применяет переранжирование по принципу максимальной предельной релевантности (устраняет кластеры почти дубликатов в top-K). mmr_lambda от 0 до 1, по умолчанию 0.7.

• category_mode: "boost" (по умолчанию) — записи совпадающей категории получают множитель 1.25× вместо отбрасывания несовпадающих. Укажите "filter" для жёсткой фильтрации.

• explain: true — добавляет score_components: {bm25, decay, maturity, confidence, category_boost, mmr_penalty} к каждому результату поиска по знаниям.

Сессии

Граф знаний

Типы знаний: related_to, supersedes, depends_on, contradicts, specializes, part_of, alternative_to, builds_on Типы структуры кода: calls, imports, inherits

Направления обхода: outbound (источник→цель), inbound (цель→источник), both (по умолчанию, ненаправленный)

Анализ

Администрирование

Продвижение с оценкой

Каждый кандидат уровня проекта оценивается по шести сигналам (релевантность 0.30, частота 0.24, разнообразие запросов 0.15, недавность 0.15, консолидация 0.10, концептуальная насыщенность 0.06) и проходит фильтрацию по minScore ≥ 0.5, minRecallCount ≥ 2, minUniqueQueries ≥ 2. Все три условия должны выполняться. Фоновое автоматическое продвижение управляется тем же флагом конфигурации auto_distill; вызывайте по требованию через knowledge_admin(action: "promote").

• promote_mode: "explain" (по умолчанию) — оценка и фильтрация кандидатов, запись в дневник, БАЗА ЗНАНИЙ НЕ ИЗМЕНЯЕТСЯ.

• promote_mode: "apply" — продвижение прошедших кандидатов, запись в дневник, git-коммит.

• Каждый запуск записывает ~/agent-knowledge/.dreams/YYYY-MM-DD.md с разбивкой сигналов по каждому кандидату и результатами фильтрации. Каталог с префиксом . отслеживается git, но исключён из списка/поиска.

• Обоснованная регидратация: кандидат пропускается, если его исходный файл сессии больше не существует на диске (предотвращает продвижение удалённого контента).

• Записи с frontmatter evergreen: true никогда не перезаписываются при продвижении — активность добавляется.

Тестовый стенд записи: npm run bench:promote — офлайн-воспроизведение с автоматической разметкой по принципу «упоминается в последующих сессиях». Сравнивает продвижение с фильтрацией с наивным базовым вариантом «продвигать всё», сообщает precision / recall / F1. Используйте его для проверки изменений весов сигналов или порогов перед развёртыванием.

REST API

Архитектура

graph LR
    subgraph Storage
        KB[(Knowledge Base<br/>~/agent-knowledge<br/>Git Repository)]
    end

    subgraph Session Sources
        CC[(Claude Code<br/>JSONL)]
        CU[(Cursor<br/>JSONL)]
        OC[(OpenCode<br/>SQLite)]
        CL[(Cline<br/>JSON)]
        CD[(Continue.dev<br/>JSON)]
        AI[(Aider<br/>MD / JSONL)]
    end

    subgraph agent-knowledge
        KM[Knowledge Module<br/>store / search / git]
        AD[Session Adapters<br/>auto-discovery]
        SE[Search Engine<br/>TF-IDF + Fuzzy]
        DS[Dashboard<br/>:3423]
        MCP[MCP Server<br/>stdio]
    end

    subgraph Clients
        AG[Agent Sessions]
        WB[Web Browser]
    end

    KB <-->|git pull/push| KM
    CC --> AD
    CU --> AD
    OC --> AD
    CL --> AD
    CD --> AD
    AI --> AD
    AD --> SE
    KM --> MCP
    SE --> MCP
    KM --> DS
    SE --> DS
    MCP --> AG
    DS --> WB

Граф знаний

Записи и символы кода могут быть связаны типизированными взвешенными рёбрами, хранящимися в отдельной таблице SQLite edges. Поддерживается одиннадцать типов связей — 8 для рёбер знаний и 3 для структуры кода:

Знания: related_to, supersedes, depends_on, contradicts, specializes, part_of, alternative_to, builds_on Структура кода: calls, imports, inherits

• knowledge_graph(action: "link") создаёт или обновляет ребро (с необязательной силой связи 0-1)

• knowledge_graph(action: "unlink") удаляет рёбра (опционально фильтруемые по типу)

• knowledge_graph(action: "list") выводит список рёбер для записи или типа связи

• knowledge_graph(action: "traverse") выполняет направленный BFS-обход от начальной записи. Поддерживает direction (outbound, inbound, both) и фильтр rel_type

• knowledge_graph(action: "bulk_link") пакетно создаёт рёбра в одной транзакции (для приёма графа кода)

• knowledge_graph(action: "unlink_by_origin") удаляет все рёбра с конкретным источником (для очистки устаревших рёбер кода перед повторным приёмом)

Граф кода

Рёбра структуры кода создаются навыком knowledge-ingest при приёме кодовой базы. Они используют идентификаторы узлов с префиксом code::

code:src/auth/middleware.ts                    # file node
code:src/auth/middleware.ts::validateToken      # symbol node

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

# Who calls validateToken?
knowledge_graph({ action: "traverse", entry: "code:src/auth.ts::validateToken", direction: "inbound", rel_type: "calls", depth: 3 })

# What breaks if I change this function?
knowledge_graph({ action: "traverse", entry: "code:src/auth.ts::validateToken", direction: "inbound", rel_type: "calls", depth: 5 })

# Combined: callers + knowledge context (decisions, design rationale)
knowledge_graph({ action: "traverse", entry: "code:src/auth.ts::validateToken", depth: 2 })

Автосвязывание

Когда knowledge с action: "write" создаёт или обновляет запись, он автоматически находит top-3 наиболее похожих существующих записей через косинусное сходство и создаёт рёбра related_to для любой пары с оценкой выше 0.7.

Оценка уверенности и затухания

Каждая запись знаний имеет оценку уверенности, отслеживаемую в таблице SQLite entry_scores. Результаты поиска ранжируются с использованием:

finalScore = baseRelevance * 0.5^(daysSinceLastAccess / 90) * maturityMultiplier

Записи автоматически созревают на основе количества обращений:

Часто запрашиваемые записи поднимаются в результатах поиска; устаревшие записи со временем теряют актуальность.

Возможности поиска

Ранжирование TF-IDF -- результаты оцениваются по частоте термина и обратной частоте документа. Редкие термины повышают релевантность. Глобальный индекс кэшируется на 60 секунд.

Нечёткое сопоставление -- расстояние Левенштейна со скользящим окном. Настраиваемый порог (по умолчанию 0.7).

Выборочное извлечение через knowledge_search с параметром scope:

Интеграции

REST-эндпоинт записи

POST /api/knowledge принимает { category, filename, content } и выполняет полный конвейер записи: git pull → запись файла → индексация эмбеддингов → автолинковка → git push → проверка дубликатов. Возвращает { path, autoLinks?, duplicateWarnings?, git } со статусом 201.

Это позволяет выполнять запись по HTTP из других сервисов без MCP-подключения.

agent-tasks KnowledgeBridge

agent-tasks имеет встроенный KnowledgeBridge, который автоматически отправляет артефакты learning и decision в agent-knowledge по завершении задачи. Записи попадают в decisions/ с frontmatter-тегами (agent-tasks, имя проекта, тип артефакта), автоматически индексируются с эмбеддингами и связываются с похожими записями. Конфигурация не требуется — если agent-knowledge запущен на localhost:3423, всё работает.

Тестирование

npm test              # 563 tests across 35 files
npm run test:watch    # Watch mode
npm run lint          # ESLint on src/ and tests/
npm run typecheck     # tsc --noEmit
npm run check         # typecheck + lint + format + test

Переменные окружения

Все переменные окружения находятся под префиксом AGENT_KNOWLEDGE_*. Никакое имя хоста не зашито — реестр адаптеров автоматически обнаруживает установленные AI-хосты для кодинга (.claude, .cursor, .codex, .aider, .continue, OpenCode) без конфигурации.

Основные

Эмбеддинги

API-ключи

Переопределения в рамках проекта имеют приоритет над стандартными ключами. Задайте любой из вариантов; форма с областью действия позволяет запускать agent-knowledge с другим ключом, чем остальная часть вашего окружения.

Хуки

Переопределения внешних инструментов

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

• Руководство по установке — установка, настройка клиентов (Claude Code, OpenCode, Cursor, Windsurf), хуки, навыки

• Руководство по импорту — навык импорта кодовой базы, извлечение tree-sitter, инкрементальные обновления

• Архитектура — структура исходников, принципы проектирования, схема базы данных

• Дашборд — представления и функции веб-интерфейса

• Журнал изменений

Лицензия

MIT