origin-memorycore

English | 简体中文

MemoryCore — это слой управления памятью для LLM-агентов.

Агенты быстро накапливают память — предпочтения, факты, решения, — и память без должного ухода незаметно деградирует: плодятся дубликаты, остаются устаревшие факты, горячий уровень переполняется и начинает отклонять записи. MemoryCore предотвращает это.

Он работает как двухуровневая система памяти:

• Горячий уровень — часто используемые поведенческие знания (предпочтения, правила, исправления) в быстром локальном файле, всегда в контексте.

• Холодный уровень — низкочастотные факты, автоматически переносимые извне и хранящиеся во встроенном движке SQLite (или в удалённом сервисе памяти, если вы его настроите).

Между ними — ядро управления, которое поддерживает память в здоровом состоянии:

• Дедупликация при записи — похожие факты объединяются до сохранения, а не дублируются.

• Контроль ёмкости — мягкий/жёсткий пороги запускают переполнение до того, как горячий уровень заполнится, поэтому он никогда не отклоняет записи.

• Управление холодным уровнем — периодические проходы дедупликации/очистки сохраняют холодный уровень доступным для поиска по мере его роста.

• Корзина — удалённые записи получают льготный период 30 дней, после чего восстанавливается. Вызов записи из корзины оживляет её.

Результат: горячий уровень остаётся в рамках бюджета, холодный уровень остаётся доступным для поиска, а память остаётся поддерживаемой независимо от того, сколько агент накопил.

Построен на стандарте MCP (Model Context Protocol) streamable-http / stdio. Работает с любым MCP-клиентом, протестирован с Hermes Agent.

Возможности

• Управление памятью (ядро) — три уровня защиты целостности данных холодного уровня:

  • Дедупликация холодной записи: перед записью в холодный уровень семантический поиск + LLM-судья проверяют дубликаты и обновляют существующие записи, вместо того чтобы создавать избыточные.

  • Жёсткий ограничитель ёмкости: холодный уровень поддерживает мягкий предел (6000 записей — запускает один проход обслуживания) и жёсткий предел (10000 записей — принудительные циклы обслуживания), предотвращая неограниченный рост.

  • Корзина (trash_store.py): удалённые записи холодного уровня перемещаются в ~/.memorycore/trash.json и хранятся там 30 дней. Возврат записи из корзины с новым семантическим подтверждением восстанавливает её («вызов для восстановления»).

• Маршрутизация «холодный/горячий» — каждая запись классифицируется: высокая важность или похожая на предпочтение → горячий (локальный); низкочастотный факт → холодный (удалённый); устаревший статус → отбрасывается.

• Шестишаговое переполнение — базовый уровень ёмкости → дедупликация → фильтрация устаревших записей → объединение → безопасная запись (сначала холодный, затем удаление локального) → проверка.

• Обслуживание холодного уровня — дедуплицирующее объединение, очистка устаревшего, разрешение конфликтов, проверка целостности эмбеддингов.

• Контроль ёмкости — мягкий порог (переполнение один раз перед записью) / жёсткий порог (принудительное переполнение) / целевое соотношение. По умолчанию: 60% / 80% / 40% от лимита в 5000 символов.

• Безопасная деградация — холодный уровень недоступен? Записи завершаются с ошибкой вслух (никогда не теряются молча), перегон при этом сохраняет локальные записи, а проверка состояния возвращает локальный статус с cold.error.

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

Related MCP server: AI Long-Term Memory MCP Server

Архитектура

┌─────────────────────────────── Mac / local ──────────────────────────────┐
│  LLM agent (e.g. Hermes)                                                 │
│    │  MCP client                                                         │
│    ▼                                                                     │
│  MemoryCore MCP server                                                   │
│    ├─ local_store.py        hot tier: MEMORY.md / USER.md (chars-based)  │
│    ├─ classifier.py         cold/hot/stale routing rules                 │
│    ├─ overflow.py           six-step overflow                            │
│    ├─ maintenance.py        cold-tier governance                         │
│    └─ cold_store_client.py  →  LocalBackend (SQLite, in-process)         │
│                               or RemoteBackend (MCP streamable-http)     │
└──────────────────────────────────────────────────────────────────────────┘
                     LocalBackend: mnemosyne-memory (in-process engine)
                     RemoteBackend: remote MCP memory service

Optional (Hermes Agent only): hermes-plugin/memorycore-prefetch
  ┌───────────────────────────────────────────────────────────────────────┐
  │ MemoryProvider plugin (single-model qwen3, enabled by default)        │
  │   system_prompt_block → static index (always active)                  │
  │   prefetch → ColdStoreClient.recall_results(top_k=20)                 │
  │            → dense ranking → session + hot-tier dedup → top-5         │
  │   Disable: MEMORYCORE_PREFETCH_ENABLED=0                              │
  └───────────────────────────────────────────────────────────────────────┘

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

Предварительные требования

• ollama — API эмбеддингов (установка: https://ollama.com)

• qwen3-embedding:0.6b — рекомендуемая модель эмбеддингов (1024-мерная)

# Install ollama (macOS/Linux)
curl -fsSL https://ollama.com/install.sh | sh

# Pull the embedding model
ollama pull qwen3-embedding:0.6b

Установка и запуск

pip install "origin-memorycore @ git+https://github.com/moonandecho/origin-memorycore.git"

# That's it! MemoryCore runs with ollama for embeddings:
#   - Hot tier:  MEMORY.md / USER.md (default ~/.hermes/memories)
#   - Cold tier: SQLite via mnemosyne-memory (default ~/.memorycore/data/)
#   - Embedding: qwen3-embedding:0.6b via ollama (http://localhost:11434/v1)
python -m memorycore.server          # stdio transport (default)

Расположение каталога данных (всё в ~/.memorycore/):

~/.memorycore/
├── data/          # SQLite database (MNEMOSYNE_DATA_DIR)
└── ...

Изменить через MNEMOSYNE_DATA_DIR.

Смена модели

Модель эмбеддингов по умолчанию — qwen3-embedding:0.6b (1024-мерная). Вы можете использовать любую модель ollama через переменные окружения:

export MEMORYCORE_EMBED_URL="http://localhost:11434/v1"
export MEMORYCORE_EMBED_MODEL="nomic-embed-text"   # or your preferred model

Либо укажите любой API эмбеддингов, совместимый с OpenAI:

export MEMORYCORE_EMBED_URL="https://api.openai.com/v1"
export MEMORYCORE_EMBED_MODEL="text-embedding-3-small"

Зарегистрируйте его в вашем MCP‑клиенте (пример для Hermes Agent config.yaml):

mcp_servers:
  memorycore:
    command: python
    args: ["-m", "memorycore.server"]

Удалённый режим (необязательно)

Если вы предпочитаете общий удалённый сервис Mnemosyne MCP вместо локального движка, установите MEMORYCORE_COLD_BACKEND=remote:

export MEMORYCORE_COLD_BACKEND=remote
export MNEMOSYNE_URL="http://your-memory-service:9000/mcp"
python -m memorycore.server

Доступные инструменты:

Интеграция с Hermes — предвыборка на каждом шаге

MCP-сервер не привязан к клиенту. Для Hermes Agent есть опциональный плагин-компаньон, который обеспечивает двухканальный доступ к холодному уровню:

Двухканальная архитектура

• Канал статического индекса (всегда активен, нулевые накладные расходы) — блок системного промпта со списком доступных тем (настраивается через MEMORYCORE_INDEX_TOPICS, разделён запятыми) и подсказка использовать memorycore_recall(query) для вызова по требованию.

• Канал предвыборки на каждом шаге (включён по умолчанию) — если включён, каждый шаг выполняется поиск по холодному уровню, ранжирование по плотности баллов и внедрение топ‑5 в контекст; таким образом, агент «вспоминает» релевантное содержимое до того, как начинает говорить. Установите MEMORYCORE_PREFETCH_ENABLED=0, чтобы отключить и использовать только вызовы по требованию.

Конвейер предвыборки

query → preprocess → cold-tier recall (20 candidates)
  → dense ranking (qwen3) → top-5
  → session dedup → hot-tier dedup → inject into context

MemoryCore использует одномодельную архитектуру qwen3 (без реранкера). Плотные баллы qwen3 используются для относительного ранжирования внутри пакетной выборки; здесь нет абсолютного порога — после дедупликации всегда внедряются 5 лучших кандидатов по баллам.

Безопасная деградация

Когда ollama недоступен (не установлен, не запущен, или модель не скачана), предвыборка молча возвращает пустую строку: диалог продолжается без внедрённых воспоминаний, ошибка никак не демонстрируется пользователю. Лог уровня DEBUG фиксирует сбой зонда.

Развёртывание (Hermes Agent)

# 1. install origin-memorycore (provides the cold tier + ColdStoreClient)
pip install "origin-memorycore @ git+https://github.com/moonandecho/origin-memorycore.git"

# 2. put the plugin in Hermes' user plugin dir
mkdir -p ~/.hermes/plugins
cp -r hermes-plugin/memorycore-prefetch ~/.hermes/plugins/

# 3. activate (takes effect next session)
hermes config set memory.provider memorycore-prefetch

После развертывания возможны три варианта:

Конфигурация плагина

Требования и примечания:

• Специфично для Hermes: плагин импортирует модули времени выполнения Hermes (agent.memory_provider) и не работает как автономный пакет — это сторона интеграции MemoryCore с Hermes. Подробности: hermes-plugin/memorycore-prefetch/README.md.

• Каждый вызов имеет таймаут 5 с; сбои сводятся к пустому внедрению и никогда не блокируют диалог.

Управление горячим уровнем

Горячий уровень (MEMORY.md / USER.md) каждый ход внедряется в контекст, поэтому должен оставаться компактным и актуальным. MemoryCore поверх шестишагового переполнения добавляет три механизма, чтобы исторические записи действительно удалялись, а не накапливались:

Старение метаданных горячего уровня

• Сопутствующие метаданные: MEMORY.meta.json / USER.meta.json лежат рядом с .md-файлами и указываются по SHA-256 от содержимого записи. Атомарные записи + блокировки файлов защищают их на уровне процессов; формат .md с разделителем § не меняется, поэтому встроенные инструменты памяти хоста работают как работали.

• Каждая запись типизируется как state (исторические решения / статусные записи) либо как rule (заповеди / предпочтения):

  • state: уходит на холодный уровень через 7 дней после записи (настраивается: STATE_TTL_DAYS).

  • rule: никогда не уходит по возрасту; после 30 дней без обновления длинные записи (> 200 символов) становятся кандидатами на сжатие с помощью LLM (настраивается: RULE_COMPRESS_DAYS). Правила также имеют управляемый выход через лестницу сигналов об инвалидации ниже — никогда не ошибаясь с активным предпочтением.

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

Двойная точка записи — управление

• Точка записи store_fact: содержимое, которое похоже на завершённое решение/статус (дата + маркер завершения типа 拍板/已配置 и отсутствие поведенческих инструкций), направляется сразу в холодный уровень — оно никогда неминует горячий.

• Прямой канал записи плагина on_memory_write: после встроенного добавления/замены записи типизируются сразу же. Объекты state мигрируют на холодный уровень в фоне (дедупликация → подтверждённая запись в холодную → удаление с горячего; если холодный успешен, запись остаётся с пометкой state как запасной на 7 дней). Этот процесс работает независимо от порогов нагрузки. Один рабочий поток обрабатывает ограниченную очередь (размер 128); когда очередь полна, запись пропускается, и её при следующем сбросе в память /*, при следующем переполнении гипер» — дотягивает как запасная.

Хм. the last segment is a bit off.

Let's revise line: "А single worker thread drains a bounded queue (size 128); when queue is full, the write is skipped and the next overflow reconcile stamps as backstop." Translation: "Один рабочий поток обрабатывает очередь ограниченного размера (128); когда очередь заполнена, запись пропускается, а при следующей сверке поратечения она будет помечена как запасная." Let's correct.

Метаданные первичное переполнение

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

Сигналы инвалидации invalidation (frac tier)

Горячий уровень, состоящий из rule-записей, по замыслу не имеет собственного выхода («предпочтение нельзя потопить»), поэтому короткие правила, которые никогда не правятся, остались бы навсегда и рано или поздно забили весь уровень. MemoryCore заполняет этот пробел с помощью лестницы давления: каждый прогон переполнения измеряет реальное значение usage (базовое) и по мере роста давления открывает более глубокие выходы (реакция). Пять наблюдаемых сигналов определяют право и порядок — давление определяет, что делать.

Холодное хранилище

Ярусная защита: мета-правила класса A (заповеди поведения / взаимодействия / стиля), правила красных линий и записи с важностью ≥ 0.9 никогда не выполняют S2/S4/S5 — только сливаются или сжимаются. Заглушки-указатели имеют собственный жизненный цикл (GC по возрасту под давлением; холодный ярус никогда не трогается), поэтому заглушка не может заполнить ярус дважды. Каждый выход — холодная запись-вперёд: локальная запись меняется только после подтверждения холодного яруса, а любой сбой сохраняет оригинал. Когда сигнал недоступен (нет журнала активности, ключа LLM), лестница деградирует к предыдущему поведению, а не гадает.

Константы (memorycore/config.py): RULE_RETYPE_DAYS=60, RULE_STUB_IDLE_DAYS=45, ACTIVITY_WINDOW_DAYS=30, MAX_STUB_PER_RUN=3, STUB_MAX_CHARS=40, IMPORTANCE_PROTECT=0.9.

Здоровье: memorycore/audit_memory

Инструмент только для чтения, список всех записей горячей ступени с их типом, возрастом, планом удержания и классификацией keep/sink каждая — якорь наблюдаемости для диагностики переполнения, который не находит ничего, во что сливать.

Масштабный тест и результаты оптимизации

MemoryCore была проверена на прочность и оптимизирована под recall в масштабе десяти тысяч записей холодного яруса (изолированная тестовая среда, ноль контакта с проданными данными, воспроизводимые результаты).

Пропускная способность записи

Задержка запроса — медиана 48м при top_k=5; шкала на десять тысяч записей совпадает со шкалой на сотню записей, регрессии задержки нет.

Качество вспоминания — три пробы:

1. Точное совпадение (самовспоминание): 20/20 лучших топ-1 — точное совпадение сохраняется.

2. Шумоподавление (несвязанные запросы): средний top-1 плотность 0.056, большинство возвращают 0.0 — несвязанный контент почти никогда не протекает в результаты.

3. Краткое вспоминание (до → после) — ключевой результат оптимизации:

Что было оптимизировано: при высокой плотности тем фиксированное сокращение кандидатов k=max(top_k, 20) выталкивало детальные воспоминания из состава кандидатов, из-за чего краткие запросы не могли вспомнить их. Исправление увеличивает сокращение кандидатов до k=max(top_k*4, 300) и расширяет кандидатов внутренне в точке входа воспоминания перед обрезанием возврата — каждый канал воспоминания (последовательное предвоспоминание + воспоминание по требованию) получает выгоду от одного исправления. Исправление ограничено стадией воспоминания; логика ранжирования не тронута, поведение предсказуемо и обратимо.

Примечание: тесты выполнялись на синтетической БД из 10 000 записей (80 «золотых» воспоминаний + 9920 в режиме ежедневного журнала, та же конфигурация, что в продакшене); продакшн-данные не посещались.

Заметки для пользователей sqlite-vec

Если вы включите векторное индексирование sqlite-vec для холодного яруса Mnemosyne, ознакомьтесь с тем, что beam.py's _wm_vec_sqlite_search использует формулу сырого сходства sim = 1 - Distance / (2 * EMBEDDING_DIM), которая схлопывает float32 расстояния до ~1.0, что делает динамический порог фактически бесполезным (все результаты проходят).

Патч: в ветке float32 замените формулу на sim = 1 — d² / 2 — это даёт точное косинусное сходство для нормализованных векторов и восстанавливает корректное пороговое поведение.

Контракт холодного хранилища

Любой сервис с этими пятью инструментами MCP может работать как холодный ярус:

См. examples/cold-store-contract.md с полным контрактом и эталонным клиентом.

Конфигурация

Константы ёмкости живут в memorycore/config.py (CHAR_LIMIT_*, SOFT_THRESHOLD, HARD_THRESHOLD, TARGET_RATIO).

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

1. Запись — store_fact классифицирует содержимое:

   • важность ≥ 0.9 или совпадение с горячими ключевыми словами (предпочтения / исправления / красные линии) → горячее, хранится локально

   • устаревшие маркеры (короткая запись, напр. "исправлено / улажено") → отбрасывается (не мигрирует)

   • всё остальное → холодное, пишется сразу в удалённый сервис

2. Переполнение — когда горячее использование пересекает мягкий порог, переполнение мигрирует низкочастотные записи в холодный ярус; при жёстком пороге оно вынужденно переполняется, пока ≤ целевому. Порядок всегда холодная запись сначала, проверка, затем удаление локалиста — ничего не теряется, если холодное хранение отказывает.

3. Обслуживание — периодическая работа над холодным ярусом объединяет дубликаты, удаляет устаревшие записи, разрешает конфликты и проверяет целостность встраивания.

Лицензия

MIT © 2026 moonandecho

Лицензии третьих сторон

• mnemosyne-memory — MIT, за авторством AxSan. Движок памяти в процессе, используемый LocalBackend.

• MCP Python SDK — MIT.

• ollama — MIT. Локальный API для эмбеддингов.

• qwen3-embedding — Apache-2.0, за авторством Alibaba Cloud. Модель эмбеддингов по умолчанию (не входит в комплект; тянется через ollama).