linksee-memory

Локальный MCP-сервер для памяти агентов. «Мозг» для совместной работы Claude Code, Cursor и ChatGPT Desktop — с кэшем diff-файлов, который экономит токены, чего не делает никто другой.

Что это делает

Большинство сервисов «памяти агентов» (Mem0, Letta, Zep) сохраняют плоский список фактов. Затем агент видит «файл X редактировался 30 раз» и не имеет понятия, почему. linksee-memory сохраняет ПРИЧИНУ (WHY).

Это сервер протокола Model Context Protocol (MCP), который дает любому ИИ-агенту четыре суперспособности:

Три столпа

1. Экономия токенов через read_smart — sha256 + разбиение на чанки по AST/заголовкам/отступам. Повторное чтение возвращает только diff. Измеренная экономия 86% при типичном редактировании TS-файла, 99% при повторном чтении без изменений.

2. Кросс-агентная переносимость — один файл SQLite по адресу ~/.linksee-memory/memory.db. Один и тот же «мозг» для Claude Code, Cursor и ChatGPT Desktop.

3. Структурированная память, ориентированная на ПРИЧИНЫ — шесть явных слоев (цель / контекст / эмоции / реализация / предостережение / обучение). Решает проблему «плоская память фактов бесполезна без целей».

Установка

npm install -g linksee-memory
linksee-memory-import --help   # bundled importer for Claude Code session history

Или используйте npx ad hoc:

npx linksee-memory             # starts the MCP server on stdio

База данных по умолчанию находится в ~/.linksee-memory/memory.db. Переопределите её с помощью переменной окружения LINKSEE_MEMORY_DIR.

Регистрация в Claude Code

claude mcp add -s user linksee -- npx -y linksee-memory

Перезапустите Claude Code. Инструменты появятся как mcp__linksee__remember, mcp__linksee__recall, mcp__linksee__recall_file, mcp__linksee__read_smart, mcp__linksee__forget, mcp__linksee__consolidate.

Опционально: автоматический захват каждой сессии (хук Stop)

Добавьте в ~/.claude/settings.json, чтобы автоматически записывать каждую сессию Claude Code в вашу локальную память:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "npx -y linksee-memory-sync" }
        ]
      }
    ]
  }
}

Завершение каждого хода занимает ~100 мс. Ошибки обрабатываются тихо (Claude Code никогда не блокируется). Логи находятся в ~/.linksee-memory/hook.log.

Инструменты

6 слоев памяти

Каждая сущность (человек / компания / проект / файл / концепция) может иметь воспоминания на шести слоях. Слой кодирует смысл, а не категорию:

{
  "goal":    { "primary": "...", "sub_tasks": [], "deadline": "..." },
  "context": { "why_now": "...", "triggering_event": "...", "when": "..." },
  "emotion": { "temperature": "hot|warm|cold", "user_tone": "..." },
  "implementation": {
    "success": [{ "what": "...", "evidence": "..." }],
    "failure": [{ "what": "...", "why_failed": "..." }]
  },
  "caveat":  [{ "rule": "...", "reason": "...", "from_incident": "..." }],
  "learning":[{ "at": "...", "learned": "...", "prior_belief": "..." }]
}

• Воспоминания caveat (предостережение) автоматически защищены от забывания (уроки на ошибках, никогда не теряются).

• Воспоминания goal (цель) обходят процесс распада, пока цель активна.

Архитектура

Один файл SQLite (better-sqlite3 + триграммный токенизатор FTS5 для JP/EN) содержит пять слоев:

• Слой 1 — entities (факты: люди / компании / проекты / концепции / файлы)

• Слой 2 — edges (ассоциации, смежность графа)

• Слой 3 — memories (6-уровневые структурированные смыслы для каждой сущности)

• Слой 4 — events (лог временных рядов для вычисления теплоты / импульса)

• Слой 5 — file_snapshots + session_file_edits (кэш diff + связь диалог↔файл)

Связь диалог↔файл является ключевой. Каждое редактирование файла, захваченное хуком Stop, сохраняется вместе с сообщением пользователя, которое привело к правке. Таким образом, recall_file("server.ts") возвращает: «этот файл редактировался 30 раз за 3 дня, и вот фактические инструкции пользователя, которые мотивировали каждое изменение».

Почему такие проектные решения

• Локально-первый — история ваших диалогов приватна. Ничего не покидает вашу машину.

• Один файл — memory.db — это один переносимый артефакт. Резервная копия = копия файла.

• MCP stdio — работает с каждым агентом, который поддерживает MCP, без плагинов для каждого хоста.

• Повторное использование проверенных схем — heat_score / momentum_score перенесены из промышленной кодовой базы анализа продаж. На основе правил, без зависимости от LLM на горячем пути.

Дорожная карта

• ✅ 6 основных инструментов MCP (remember / recall / recall_file / forget / consolidate / read_smart)

• ✅ Автоматический захват через хук Stop для Claude Code

• ✅ Триграммный FTS5 для JP/EN

• 🚧 Хук PreToolUse для автоматического перехвата Read (экономия токенов без настройки)

• 🚧 Адаптеры для Cursor + ChatGPT Desktop

• 🔮 Векторный поиск через sqlite-vec после выбора бэкенда эмбеддингов (Ollama / API / и т.д.)

• 🔮 Опциональная анонимизированная телеметрия → слой интеллекта качества MCP

Сравнение с Claude Code auto-memory

Claude Code поставляется со встроенной функцией памяти в ~/.claude/projects/<path>/memory/*.md — плоские markdown-заметки для предпочтений пользователя. linksee-memory дополняет её:

• auto-memory = ваш блокнот «запомни, что я предпочитаю X»

• linksee-memory = структурированный кросс-агентный мозг с кэшем diff-файлов и ПРИЧИНОЙ каждой правки

Используйте оба.

Телеметрия (опционально, по умолчанию выключена)

linksee-memory поставляется с опциональной анонимной телеметрией, которая помогает нам понять, какие MCP-серверы и рабочие процессы действительно работают в реальных условиях. Ничего не отправляется, пока вы явно не включите это. Никакого содержимого диалогов, никакого содержимого файлов, никаких имен сущностей, никаких путей к проектам — никогда.

Включение

export LINKSEE_TELEMETRY=basic     # opt in
export LINKSEE_TELEMETRY=off       # opt out (or just unset the variable)

Что именно отправляется (контракт уровня 1)

После завершения каждой сессии Claude Code хук Stop отправляет один POST на https://kansei-link-mcp-production.up.railway.app/api/telemetry/linksee, содержащий только эти поля:

Что НИКОГДА не отправляется:

• ❌ Сообщения диалога (пользователя или ассистента)

• ❌ Содержимое файлов

• ❌ Имена сущностей, названия проектов, пути к файлам, URL-адреса

• ❌ Текст слоев памяти (цель / контекст / эмоции / реализация / предостережение / обучение)

• ❌ Токены аутентификации, API-ключи, секреты

• ❌ Ваш IP-адрес (только односторонний хеш для обнаружения злоупотреблений)

Зачем мы просим

Агрегированные данные об использовании MCP помогают проекту KanseiLink ранжировать, какие агентные интеграции действительно работают для реальных разработчиков. Если вы хотите внести свой вклад, установка LINKSEE_TELEMETRY=basic занимает 1 секунду и помогает улучшить всю экосистему MCP.

Полная схема полезной нагрузки и логика валидации являются открытым исходным кодом — прочитайте src/lib/telemetry.ts, если хотите проверить, что именно покидает вашу машину.

Лицензия

MIT — Synapse Arrows PTE. LTD.