khwan-mcp

Долговременная память, переживающая сессию. Сервер MCP, который подключает Khwan — чисто AI-слой памяти — к Claude Code, Claude Desktop или любому MCP-клиенту.

Khwan никогда не запускает модель. Клиент — и есть модель. Его задача — сохранять и дистиллировать в мозг то, что важно, чтобы его можно было восстановить в более поздней сессии или передать субагенту — компактный, ограниченный набор фактов вместо повторного транскрипта. Один аккаунт может содержать множество изолированных ядер (мозгов), а на платных тарифах — изолированный суб-мозг для каждого конечного пользователя.

Как экономит токены (и где — нет)

Скажем честно о механизме: MCP добавляет контекст хосту, он не может заменить транскрипт, который хост уже отправляет. Поэтому:

• Внутри одной горячей сессии токены он не экономит. Claude Code кэширует свою растущую историю (чтение из кэша ≈ 0.1×), так что повторное внедрение памяти на каждом ходе только добавляет. Не делайте так здесь.

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

Экономящая токены схема: затравка один раз, запоминание устойчивых фактов (ниже), а не полный цикл на каждый ход кэширующего хоста. Полный цикл prepare → record по-прежнему хорош в кастомном агенте на некэширующем хосте, где замена истории дистиллированной памятью напрямую ограничивает стоимость каждого хода.

Related MCP server: LedgerMem MCP Server

Установка

pip install khwan-mcp          # or: uvx khwan-mcp

Подключение к Claude Code

claude mcp add khwan --scope project \
  -e KHWAN_CORE=default \
  -- khwan-mcp

--scope project записывает .mcp.json в репозиторий, поэтому настройка путешествует вместе с проектом. Обратите внимание, чего нет в этой команде: ключа.

Хранение ключа вне репозитория

claude mcp add -e KHWAN_API_KEY=… записывает буквальное значение в .mcp.json — файл, весь смысл которого в коммите. Есть два способа этого избежать, и второй — тот, который работает везде:

Переменные окружения шелла. Полностью исключите KHWAN_API_KEY из конфигурации и экспортируйте его в шелле, который запускает claude. Сервер унаследует.

export KHWAN_API_KEY=kwk_live_xxx

Запускающий скрипт (работает и в десктоп-приложении). Десктоп-приложение запускается из дока или меню, а не из логин-шела, поэтому оно не наследует ни одного экспорта вашей оболочки, и описанный выше подход молча остаётся без ключа. Вместо этого прочитайте ключ из файла:

mkdir -p ~/.khwan && chmod 700 ~/.khwan
printf 'KHWAN_API_KEY=kwk_live_xxx\n' > ~/.khwan/env && chmod 600 ~/.khwan/env

cat > ~/.khwan/khwan-mcp <<'SH'
#!/bin/sh
set -a
[ -f "$HOME/.khwan/env" ] && . "$HOME/.khwan/env"
set +a
exec khwan-mcp "$@"
SH
chmod 700 ~/.khwan/khwan-mcp

Затем настройте конфиг на запускающий скрипт и оставьте в нём только несекретные параметры:

claude mcp add khwan --scope project \
  -e KHWAN_CORE=acme -e KHWAN_USER=Web \
  -- ~/.khwan/khwan-mcp

.mcp.json теперь безопасно коммитить, и каждый новый репозиторий обходится двумя строками вместо вставленного ключа. Остальные участники команды пишут собственный ~/.khwan/env.

Один мозг на проект

Память полезна только тогда, когда возвращается память нужного проекта. Две оси, и обе дают полную изоляцию:

Суб-мозг — это полностью отдельный мозг, а не фильтр: account::acme::@Web не делится ничем с account::acme::@Api. Поэтому клиент с несколькими репозиториями может быть одним ядром с отдельным суб-мозгом для каждого, а не отдельным ядром для каждого:

# in ~/code/acme-web
claude mcp add khwan --scope project -e KHWAN_CORE=acme -e KHWAN_USER=Web -- ~/.khwan/khwan-mcp
# in ~/code/acme-api
claude mcp add khwan --scope project -e KHWAN_CORE=acme -e KHWAN_USER=Api -- ~/.khwan/khwan-mcp

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

Рекомендуемая схема (экономящая токены)

На кэширующем хосте, таком как Claude Code, предпочитайте затравку + запоминание, а не цикл на каждый ход:

1. Затравка в начале сессии или у субагента:

   «Вызовите khwan_recall(query="<the task>") и используйте возвращённый seed_text как контекст».

2. Запоминание устойчивых фактов по мере их появления:

   „Это постоянное решение — вызовите khwan_remember(fact="…")».

Закрепите это в CLAUDE.md вашего проекта, например:

- At the start of a task, call `khwan_recall` to seed relevant memory.
- When a durable decision/preference/fact emerges, call `khwan_remember`.
- Don't call prepare/record every turn — it adds tokens without saving them here.

Затравка субагента — где выигрыш наиболее очевиден: передайте ему ограниченное краткое описание, а не весь транскрипт:

«Восстановите память о деплое через khwan_recall(query="deploy runbook"), а затем создайте субагента, чей бриф — этот seed_text плюс задача».

Подключение к Claude Desktop

У Claude Desktop и Claude Code раздельные MCP-конфигурации — сервер, добавленный в один, не виден в другом, а claude mcp add не трогает этот файл. Добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "khwan": {
      "command": "/Users/you/.khwan/khwan-mcp",
      "env": {
        "KHWAN_CORE": "acme",
        "KHWAN_USER": "Web"
      }
    }
  }
}

Используйте абсолютный путь: десктоп-приложение не получает PATH из вашего шелла, поэтому простое khwan-mcp может не найтись. Для всего приложения выбирается одно ядро — здесь нет переключения по проектам, поэтому выбирайте широкое.

Конфигурация (переменные окружения)

Инструменты

khwan_recall / khwan_remember — это пара, экономящая токены, для кэширующего хоста; khwan_prepare / khwan_record — полный цикл для кастомных агентов (передавайте точный turn_token из prepare обратно в record).

Что возвращается и что означает пустой ответ

khwan_recall возвращает не более трёх фактов — этот потолок задаёт сервер, поэтому limit может его снизить, но не повысить, — плюс любые lessons, которые синтез извлёк из многих прошлых ходов. Lessons идут в начале seed_text: правило, выработанное месяцами, важнее одиночного хода, который просто оказался рядом в индексе.

Поиск использует нижний порог релевантности, поэтому пустые facts — это тоже ответ: у мозга нет ничего близкого по этому вопросу. Воспринимайте это как «здесь неизвестно», а не как сбой, и не заполняйте пробел, хватаясь за ближайший найденный факт.

Потолок намеренно низкий, потому что неверно отброшенная память невидима, а неверно сохранённая — заметна. Ждите, что возвращённый факт будет правдоподобно связан, но не гарантированно релевантен, — прочитайте его, прежде чем полагаться на него.

Загрузка мозга из уже проделанной работы

Новый мозг ничего не знает, поэтому первые недели ответов скудные — хотя ответы часто уже лежат в собственных транскриптах хоста, непрочитанные. examples/backfill/ воспроизводит транскрипты Claude Code в мозге: детерминированно, без вызовов модели, по умолчанию в режиме сухого прогона.

python3 examples/backfill/backfill_claude_code.py --map cores.json

Всегда включённая память (хуки Claude Code)

Инструменты выше вызываются когда решает Claude. Для детерминированной памяти — без зависимости от модели — используйте пресет в examples/claude-code-hooks/: хук UserPromptSubmit добавляет память в каждый промпт, а хук Stop записывает каждый ответ.

⚠️ На кэширующем хосте это ″новный*, а не дешёвый вариант — он добавляет токены на каждый ход. Предпочитайте его, когда надёжность вспоминания важнее стоимости токенов (или на некэширующем клиенте); иначе используйте khwan_recall в начале сессии.

Источник

github.com/khwanlabs/khwan-mcp — этот сервер работает на вашей машине, с вашим ключом и читает то, что вы печатаете. Прочитайте его перед установкой.

Лицензия

MIT — © Khwan Labs. См. LICENSE.