Roampal — MCP-сервер для персистентной памяти на основе результатов

Зачем?

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

Roampal — это MCP-сервер, который дает вашему ИИ персистентную память на основе результатов для каждой сессии. Хорошие советы получают приоритет. Плохие советы понижаются в рейтинге. Ваш ИИ учится тому, что работает, а что нет — автоматически, без изменения вашего рабочего процесса.

Бенчмарки

85.8% в LoCoMo (несостязательная точность ответов end-to-end) — проверено на 1986 вопросах в 10 диалогах с двойной оценкой.

Конвейер бенчмарков работает на одном GPU без зависимостей от облака. Сам Roampal работает на CPU — GPU не требуется. Полная методология, данные и скрипты оценки: roampal-labs

Статья: "Beyond Ingestion: What Conversational Memory Learning Reveals on a Corrected LoCoMo Benchmark" (Логан Тиг, апрель 2026 г.)

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

pip install roampal
roampal init

Автоматически обнаруживает установленные инструменты. Перезапустите редактор и начните общение.

Выберите конкретный инструмент: roampal init --claude-code или roampal init --opencode

Основной цикл идентичен — обе платформы внедряют контекст, фиксируют обмен данными и оценивают результаты. Механизм доставки различается:

Claude Code запрашивает основную LLM для оценки каждого обмена через инструмент score_memories. OpenCode никогда не оценивает себя сам — независимый сайдкар (отдельный вызов API) проверяет каждый обмен как третья сторона, устраняя предвзятость самооценки. Инструмент score_memories не регистрируется в OpenCode. Во время roampal init или roampal sidecar setup Roampal обнаруживает локальные модели (Ollama, LM Studio и т.д.) и позволяет выбрать модель для оценки. Если они настроены, они имеют приоритет (Zen пропускается для конфиденциальности). Дешевая или локальная модель отлично справляется — для оценки не нужна мощная модель. Если пропустить настройку, по умолчанию используются бесплатные модели Zen (удаленные, best-effort).

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

Когда вы вводите сообщение, Roampal автоматически внедряет релевантный контекст до того, как его увидит ваш ИИ:

Вы вводите:

fix the auth bug

Ваш ИИ видит:

═══ KNOWN CONTEXT ═══
• JWT refresh pattern fixed auth loop [id:patterns_a1b2] (3d, 90% proven, patterns)
• User prefers: never stage git changes [id:mb_c3d4] (memory_bank)
═══ END CONTEXT ═══

fix the auth bug

Никаких ручных вызовов. Никаких изменений в рабочем процессе. Это просто работает.

Цикл

1. Вы вводите сообщение

2. Roampal внедряет релевантный контекст автоматически (хуки в Claude Code, плагин в OpenCode)

3. ИИ отвечает, полностью осознавая вашу историю, предпочтения и то, что работало раньше

4. Результат оценивается — хорошие советы получают приоритет, плохие понижаются

5. Повтор — система становится умнее с каждым обменом

Пять коллекций памяти

Команды

roampal init                # Auto-detect and configure installed tools
roampal init --claude-code  # Configure Claude Code explicitly
roampal init --opencode     # Configure OpenCode explicitly
roampal init --no-input     # Non-interactive setup (CI/scripts)
roampal start               # Start the HTTP server manually
roampal stop                # Stop the HTTP server
roampal status              # Check if server is running
roampal status --json       # Machine-readable status (for scripting)
roampal stats               # View memory statistics
roampal stats --json        # Machine-readable statistics (for scripting)
roampal doctor              # Diagnose installation issues
roampal summarize           # Summarize long memories (retroactive cleanup)
roampal score               # Score the last exchange (manual/testing)
roampal context             # Output recent exchange context
roampal ingest <file>       # Add documents to books collection
roampal books               # List all ingested books
roampal remove <title>      # Remove a book by title
roampal sidecar status      # Check scoring model configuration (OpenCode)
roampal sidecar setup       # Configure scoring model (OpenCode)
roampal sidecar test        # Test scoring model response format (OpenCode)
roampal retag               # Re-extract tags on memories using sidecar LLM
roampal sidecar disable     # Remove scoring model configuration (OpenCode)

Инструменты MCP

Ваш ИИ получает следующие инструменты памяти:

Как работает оценка: Хуки Claude Code запрашивают основную LLM для вызова score_memories на каждом шаге. OpenCode использует независимый сайдкар, который оценивает данные в фоновом режиме — модель никогда не видит промпт оценки, а score_memories не регистрируется как инструмент. Если сайдкар недоступен, предупреждение предложит пользователю запустить roampal sidecar setup. Выберите модель оценки во время roampal init или через roampal sidecar setup.

Сравнение Roampal

┌─────────────────────────────────────────────────────────┐
│  pip install roampal && roampal init                    │
│    Claude Code: hooks + MCP → ~/.claude/                │
│    OpenCode:    plugin + MCP → ~/.config/opencode/      │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  HTTP Hook Server (port 27182)                          │
│    Auto-started on first use, self-heals on failure     │
│    Manual control: roampal start / roampal stop         │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  User types message                                     │
│    → Hook/plugin calls HTTP server for context          │
│    → AI sees relevant memories, responds                │
│    → Exchange stored, scored (hooks or sidecar)         │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  Single-Writer Backend                                  │
│    FastAPI → UnifiedMemorySystem → ChromaDB             │
│    All clients share one server, isolated by session    │
└─────────────────────────────────────────────────────────┘

См. dev/docs/ для получения полных технических деталей.

Требования

• Python 3.10+

• Один из: Claude Code или OpenCode

• Платформы: Windows, macOS, Linux (в основном разработано и протестировано на Windows)

• RAM: ~800 МБ свободно (кросс-энкодер переранжирования + эмбеддинги + ChromaDB)

• Диск: ~500 МБ для моделей (мультиязычные эмбеддинги + переранжировщик, загружаются автоматически при первом использовании)

• CPU: Любой современный процессор x86-64 с AVX2 (Intel Haswell 2013+ / AMD Excavator 2015+)

• GPU: Не требуется — все вычисления выполняются на CPU через ONNX Runtime

Устранение неполадок

• Перезапустите Claude Code (хуки загружаются при запуске)

• Проверьте HTTP-сервер: curl http://127.0.0.1:27182/api/health

• Убедитесь, что в ~/.claude.json есть запись MCP roampal-core с правильным путем к Python

• Проверьте панель вывода Claude Code на наличие ошибок MCP

• Убедитесь, что вы запустили roampal init --opencode

• Проверьте, что сервер запустился автоматически: curl http://127.0.0.1:27182/api/health

• Если нет, запустите его вручную: roampal start

Это ожидаемое поведение. У Roampal есть самовосстановление — если HTTP-сервер перестает отвечать, он автоматически перезапускается и повторяет попытку.

Все еще не получается? Попросите ваш ИИ помочь — он может читать логи и отлаживать проблемы Roampal напрямую.

Поддержка

Roampal Core полностью бесплатен и имеет открытый исходный код.

• Поддержать разработку: roampal.gumroad.com

• Идеи функций и обратная связь: Discord

• Сообщения об ошибках: GitHub Issues

• Нужна помощь с ИИ-памятью? Пишите: roampal@protonmail.com | LinkedIn

Лицензия

Apache 2.0