📜 Litopys

Живая летопись для вашего ИИ.

Постоянная графовая память, которая сохраняется между сессиями и клиентами. Создана для Claude Code, Claude Desktop и любого агента, совместимого с MCP.

litopys-dev.github.io/litopys — установка, скриншоты и быстрое начало работы

🇺🇦 Читати українською

Зачем нужен Litopys?

Современные системы памяти для ИИ-агентов заставляют идти на компромисс: либо тяжелые векторные базы данных с утечками подпроцессов и потреблением ~500 МБ ОЗУ, либо простые markdown-файлы, которые не масштабируются дальше нескольких десятков заметок.

Litopys предлагает третий путь: типизированный граф знаний, хранящийся в обычном markdown, работающий через легкий слой MCP (~75 МБ ОЗУ), редактируемый вручную и доступный для запросов как по ключевым словам, так и по структуре. Litopys означает «летопись» на украинском — потому что именно этим и должна быть память вашего ИИ: живой записью того, что он узнал о вас, когда и почему.

Related MCP server: auxly-memory-cli

Возможности

• 🧠 Типизированный граф — 6 типов узлов (человек, проект, система, концепция, событие, урок) с 11 первоклассными типами связей

• 🔌 MCP-native — работает с Claude Code, Claude Desktop, Cursor, Cline или любым клиентом MCP (см. docs/integrations)

• 📝 Markdown-first — каждый узел является обычным файлом .md с YAML-заголовком. Можно редактировать вручную, искать через grep, версионировать в git

• 🤖 Модельно-независимый экстрактор — Anthropic, OpenAI или локальная Ollama. Выбирайте в зависимости от вашего бюджета ресурсов/средств (см. Расход ресурсов ниже). Факты проходят через карантин, поэтому ничего не попадет в базу без проверки

• 🌐 Веб-панель управления — просматривайте, ищите, редактируйте, визуализируйте граф и проверяйте карантин по адресу http://localhost:3999

• 🔐 Локальное хранение — граф живет в ~/.litopys/graph/ в виде файлов; сервер по умолчанию привязывается к 127.0.0.1; никакой телеметрии

Панель управления

Скриншоты сделаны на основе синтетического демо-графа, входящего в комплект docs/screenshots/ — это не личные заметки автора.

Статус

Вышел v0.1.2 — готовые бинарные файлы для Linux / macOS / Windows (x64 + arm64) с контрольными суммами SHA-256, проверяемыми через install.sh. Релиз безопасности поверх стабильной ветки v0.1.1 — см. CHANGELOG. Публичные интерфейсы (инструменты MCP, CLI, экспорт JSON schemaVersion: 1, структура markdown на диске) заморожены; критические изменения будут выпускаться в версии 0.2.x.

Основной граф, MCP-сервер (5 инструментов, stdio + HTTP/SSE), экстрактор + карантин + еженедельный дайджест, таймер-демон, панель управления (чтение + запись + визуализация графа + проверка карантина), механизмы защиты идентификации, сборка в один бинарный файл, установщик в одну строку, документация по интеграции для каждого клиента — всё готово. См. Что дальше для планируемых обновлений.

Расход ресурсов

Честные цифры из личной установки автора (Ubuntu, Bun 1.x). MCP-сервер потребляет мало; экстрактор — это то, где возникают расходы, и они зависят от выбранного адаптера.

Таким образом, минимальный расход составляет ~75 МБ для MCP-сервера. Извлечение опционально — вы можете использовать Litopys только для чтения/записи из вашего агента и никогда не запускать демона. Если вы включите извлечение, вариант с локальной Ollama меняет деньги на ОЗУ; вариант с Anthropic/OpenAI меняет ОЗУ на центы за сессию. Параметр keep_alive в Ollama означает, что показатели 3B/7B временны — модель выгружается из ОЗУ через несколько минут после завершения тика.

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

Установка в одну строку (Linux / macOS):

curl -fsSL https://raw.githubusercontent.com/litopys-dev/litopys/main/install.sh | sh

Это скачивает один бинарный файл (~100 МБ) в ~/.local/bin/litopys, инициализирует ~/.litopys/graph/ с необходимыми поддиректориями и выводит подсказки по регистрации MCP.

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

curl -fsSL https://raw.githubusercontent.com/litopys-dev/litopys/main/install.sh | LITOPYS_VERSION=v0.1.2 sh

Затем зарегистрируйте MCP-сервер в вашем клиенте:

# Claude Code
claude mcp add litopys -- ~/.local/bin/litopys mcp stdio

// Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "litopys": {
      "command": "/home/you/.local/bin/litopys",
      "args": ["mcp", "stdio"]
    }
  }
}

Перезапустите клиент. Ресурс litopys://startup-context автоматически загружает профиль владельца, активные проекты, недавние события и ключевые уроки при каждой новой сессии. Агент читает/пишет через пять инструментов MCP: litopys_search, litopys_get, litopys_related, litopys_create, litopys_link.

Полные инструкции для конкретных клиентов находятся в docs/integrations/ — Claude Code, Claude Desktop, Cursor, Cline, ChatGPT Connectors, Gemini.

Удаленный режим (HTTP/SSE)

Для удаленных клиентов (коннекторы Claude Desktop, MCP-хосты в браузере):

LITOPYS_MCP_TOKEN=your-secret litopys mcp http
# listens on 127.0.0.1:7777 by default
# set LITOPYS_MCP_BIND_ADDR=0.0.0.0 + TLS proxy for remote exposure
# set LITOPYS_MCP_CORS_ORIGIN=https://your-client to enable CORS

Установка для разработки (из исходного кода)

git clone https://github.com/litopys-dev/litopys.git
cd litopys
bun install
bun run build:binary       # produces dist/litopys

Опционально — демон для долгоживущих транскриптов

cp packages/daemon/systemd/litopys-daemon.{service,timer} ~/.config/systemd/user/
systemctl --user enable --now litopys-daemon.timer

Опционально — автозапуск веб-панели

Панель управления (litopys viewer) может работать как пользовательская служба systemd, чтобы она возвращалась после каждой перезагрузки.

litopys viewer install        # generates token, writes unit, enables service
litopys viewer install --lan  # same + binds to 0.0.0.0 for LAN access
systemctl --user status litopys-viewer

# Remove:
litopys viewer uninstall

Токен доступа. viewer install автоматически генерирует случайный токен и сохраняет его в ~/.litopys/viewer.token. Вывод установки печатает готовый к использованию URL со встроенным токеном:

✓ litopys-viewer installed

  Open dashboard:    http://localhost:3999/?token=<token>
  Share with others: http://192.168.1.x:3999/?token=<token>   # --lan only

  Opening the link once saves the token — no re-entry needed.
  Retrieve token later: cat ~/.litopys/viewer.token

Открытие URL один раз сохраняет токен в localStorage — больше никаких запросов. Чтобы поделиться доступом на запись с кем-то, отправьте им URL, который включает ?token=…. Чтобы получить токен в любое время: cat ~/.litopys/viewer.token.

GET-эндпоинты (просмотр, поиск, вид графа) всегда открыты. Мутирующие эндпоинты (создание / редактирование / удаление узлов, принятие или отклонение карантина) требуют токен.

Или установите LITOPYS_ENABLE_VIEWER=1 при запуске install.sh, чтобы включить его как часть установки в одну строку. Требуется loginctl enable-linger $USER, если вы хотите, чтобы панель управления оставалась активной после выхода из системы.

Проверка целостности

litopys check           # human-readable report, grouped by error kind
litopys check --json    # { nodeCount, edgeCount, errorCount, errors[] } for CI

Загружает и разрешает весь граф, затем помечает битые ссылки, дубликаты ID, связи с неверным типом и ошибки парсинга/валидации. Завершается с ненулевым кодом при обнаружении проблем — добавьте это в git pre-push хук или шаг CI, чтобы ошибки никогда не попадали в базу незаметно.

Резервное копирование графа

Litopys хранит всё как обычный markdown в ~/.litopys/graph/, поэтому работает любой инструмент, версионирующий файлы. Два распространенных подхода:

Git + приватный удаленный репозиторий (инкрементальная история, вне сайта, бесплатно):

cd ~/.litopys
git init
git add graph/ .gitignore README.md
git commit -m "baseline"
gh repo create my-litopys-graph --private --source=. --push

С этого момента каждый хук завершения сессии или ручное принятие оставляет рабочее дерево «грязным» — периодически делайте git add -A && git commit -m "sync" && git push, чтобы поддерживать резервную копию в актуальном состоянии. Ваш граф содержит личные факты, поэтому держите удаленный репозиторий приватным.

JSON-снимок (портативный, удобный для diff, дружелюбный к инструментам):

litopys export > graph.json              # compact
litopys export --pretty > graph.json     # indented, VCS-friendly
litopys export --no-body > meta.json     # metadata only, strip markdown bodies

Дамп содержит meta (exportedAt, counts, schemaVersion) плюс все узлы, отсортированные по ID, и ребра, отсортированные по (from, relation, to) — детерминировано между запусками, поэтому diff graph-yesterday.json graph-today.json точно покажет, что добавил LLM/демон. Передавайте его в инструменты анализа, переносите между хостами или коммитьте вместе с кодом.

Восстановление из снимка на новом хосте (или после переустановки):

litopys import graph.json --dry-run   # preview the plan
litopys import graph.json             # create new nodes, skip existing ones
litopys import graph.json --force     # also overwrite existing ids

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

История релизов

См. CHANGELOG.md. Будущая работа определяется отзывами реальных пользователей — откройте issue, если что-то не устраивает.

Принципы проектирования

• Агентно-независимый. Нет жесткой зависимости от какого-либо поставщика LLM или клиента. MCP — единственная точка интеграции. Ollama — экстрактор по умолчанию; Anthropic/OpenAI — опциональные адаптеры.

• Портативные данные. Граф — это обычный markdown + YAML-заголовок на диске. Читается в любом редакторе, версионируется в git, доступен для поиска из оболочки.

• Легкая среда выполнения. ~75 МБ ОЗУ для MCP-сервера. Экстрактор работает вне процесса и запускается по вашему расписанию, а не при каждом запросе — см. Расход ресурсов для полного анализа затрат по адаптерам.

• Опциональные интеграции. Вспомогательные инструменты для конкретных клиентов (хуки, фрагменты конфигурации) находятся в docs/integrations/ — вы можете использовать Litopys без них.

Лицензия

MIT © 2026 Denis Blashchytsia и участники Litopys.