realMemory

Постоянный слой памяти для LLM-агентов с непрерывным обучением: локальная «гиппокампальная» память, которая пишет без переиндексации, забывает через динамику следов и консолидирует эпизоды в семантику во время «сна».

Статус: v0.4 — единое хранилище SQLite, общее для всех процессов, глобальная/проектная области памяти, гибридный поисκ FTS5, пороги, откалиброванные на реальных текстах.

Суть идеи

LLM остаётся замороженной («кортексом»). realMemory — это отдельный изменяемый модуль («гиппокамп»):

• Запись, управляемая новизной: известный факт потенцируется, родственный — связывается, новый — получает новый след. Переформулировки никог да не наκапливаются.

• Общая и попроектная память: каждый след несёт область (global или имя проекта); припоминание видит текущий проект плюс global и никог да не смешивает контексты.

• Забывание из динамиκи следов: сохраняемость каждого следа затухает экспоненциально, подκрепления продлевают его жизнь, достаточно подκреплённые эпизоды повышаются до семантических следов (медленное затухание). Кривая забывания — свойство синапса, а не cron-задачи.

• Ассоциативный граф бесплатно: всё, что припоминалось вместе, связывается пластичностью (правило, подобное STDP) — многошаговый обход возникает из статистики использования, а не из извлечения сущностей LLM.

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

• Сон: офлайн-консолидация фиксирует следы элигибильности, затухает/обрезает слабые связи и повышаеτ статусы. Всё состояние живёт в одной базае SQLite: MCP-сервер и хуки работают одновременно без потери данных.

Related MCP server: Cortex

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

pip install -e ".[dev]"
pytest                # full core test suite
python -m realmemory.eval.bench_recall --facts 1500 --queries 200   # synthetic
python -m realmemory.eval.bench_real                                # real-text (fastembed)

from realmemory import Hippocampus, MemoryConfig

hippo = Hippocampus.open("./rm_data", config=MemoryConfig.dev())
hippo.remember("The project uses PostgreSQL 16 with alembic migrations",
               scope="myproject")            # a project-scoped fact
hippo.remember("The user prefers concise answers") # global by default

packet = hippo.recall("which database does the project use?", scope="myproject")
for item in packet.items:
    print(f"[{item.confidence:.2f}] ({item.source}) {item.text}")
if packet.abstained:
    print("no trustworthy memories")     # abstention instead of hallucination

hippo.consolidate()   # "sleep": commit traces, decay weak links

Локальный эмбеддер

По умолчанию ядро использует детерминированный HashingEmbedder (без моделей). Локальный семантический эмбеддер для продаκшена — fastembed (ONNX Runtime, CPU):

pip install 'realmemory[local]'

• Модель: paraphrase-multilingual-MiniLM-L12-v2, dim=384, русский+английский.

• Кэш моде ли: ~/.cache/realmemory/fastembed (~240 МБ), загружаеτся один раз.

• Измеренная нагруза: ~580 МБ ОЗУ процесса; ~65–75 мс на тек ст на CPU; полное припоминание ≈ 77 мс. Для агента незаметно.

• Асимметрия учтена: факты кодируются embed(), запросы — embed_query().

• Пороги гейта откалиброваны по анизотропии модели: профиль порогов находится в FastEmbedProvider.recommended_thresholds, применяется при старте сервера и выведен из бенчмарка на реальных текстах (см. ниже).

Подключение к ZCode / Claude Code (MCP)

Зарегистрируйте stdio-сервер в области пользователя в конфигурации клиента:

"realmemory": {
  "type": "stdio",
  "command": "/path/to/venv/Scripts/python.exe",
  "args": ["-m", "realmemory.api.mcp_server",
           "--path", "/path/to/rm_data",
           "--embedder", "local"]
}

Инструменты агента (названные как когнитивные действаия): recall(query,k,project) · memorize(text,kind,related_ids,project) · reflect(memory_ids,reward) · revise(old_id,new_text) · introspect() · dream_log().

Общая и попроектная память: каждый след помечен областью — global (предпочтения, идентичность) или именем проекта. Проект определяется автоматически (REALMEMORY_PROJECT → ZCODE_PROJECT_DIR → текущий каталог, содержащий .git); его также можно передать явно через аргумент project или --project. recall ищет в текущем проекте + global; другие проекты никогда не просачиваются.

Полная изоляция пространства имён между отдельными мозгами доступна через Hippocampus.open(path, namespace=...) / --namespace.

База данных хранит маркер эмбеддера (db_meta) и отказывается открываться с другим — старые и новые векторы несравнимы по косинусу.

Автоматизация: как заставить агентов реально использовать это

Три механизма, устанавливаемые по умолчанию:

1. Скилл / инструкции, описывающие, когда припоминать / запоминать / рефлексировать, загружаемые в контекст каждой сессии.

2. Хук SessionStart → python -m realmemory.hook_cli brief — внедряет краткое состояние памяти: семантические факты и устойчивые эпизодические следы текущего проекта + global, бюджет ~600 символов.

3. Хук Stop → python -m realmemory.hook_cli sleep — консолидация после каждого ответа; ограничивается состоянием базы данных (пропускается, если с последнего сна ничего не изменилось). Занимает ~0,3 с, не загружает модель эмбеддера.

Хуки и MCP-сервер безопасно работают одновременно: всё состояние в SQLite, конкурентные «сны» сериализуются транзакцией.

Эксплуатация

• Резервные копии: перед каждым «сном» база данных копируется в <store>/backups/ (консистентный API резервного копирования SQLite), хранятся последние 10 копий (backups_keep; 0 отключает). Любая миграция схемы сначала делает автоматическую предохранительную копию.

• Версия схемы записывается в db_meta.schema_version.

• Сбои хуков не молчат: упавший хук печатает в stderr сессии и оставляет событие hook_error в журнале, видимое в отчёте.

• Дисциплина обучения: отчёт показывает reflect/recall — ниже ~0.1 агент редко оценивает припомненные воспоминания, и затухание/повышение работают вслепую.

• Маршрутизация проектов проверяется одним вызовом — introspect показывает текущий определённый проект.

Наблюдаемость («как память ведёт себя со временем»)

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

python -m realmemory.report --path ./rm_data [--json report.json]

Показывает: рост памяти по типу/области/статусу, историю решений гейта новизны, долю абстенции и задержку припоминания p50/p95, что получило подкрепление, какие эпизоды затухают, динамику сохранности между снами, сбои хуков.

Результаты фазы 0 (реальные прогоны)

Синтетический бенчмарк (bench_recall, хэширующий эмбеддер, dim=2048):

Бенчмарк на реальных текстах (bench_real, fastembed MiniLM dim=384, 103 факта RU/EN, 89 запросов — перефразировки, точные токены, шум):

Урок из синтетического бенчмарка: он показал 1.000, тогда как пороги по умолчанию на реальном тексте сливали почти всё в несколько «сгустков» — теперь калибровка выводится из распределений бенчмарка и живёт в профиле эмбеддера.

Тот же бенчмарк на реальных текстах включает наивный базовый полный перебор по косинусу: пайплайн явно выигрывает на точных токенах (1.000 против 0.800), не уступает на перефразировках и в настоящее время воздерживается от ответа менее агрессивно, чем чистый порог — см. docs/ARCHITECTURE.md §7.2.

Прогон по масштабу (10k–50k следов) с честными выводами об обрыве качества припоминания на 30k на синтетических данных: §7.3.

Подробности и отрицательный результат Hamming-SDM — в docs/ARCHITECTURE.md, §3 и §7.

Тесты: 122 пройдено.

Архитектура

Кратко: L1 — SDRVotingIndex, голосование указателей по инвертированному индексу SDR-единиц (ёмкость + кандидаты), L2 — сеть ансамблей над теми же единицами (ассоциации, завершение, многошаговость), сверху — точный реранк по эмбеддингам, гейт новизны, политики затухания и офлайн-консолидатор («сон»).

Интерфейсы модулей зафиксированы в docs/CONTRACTS.md; научная подоплёка и источники — в docs/RESEARCH.md.

Структура проекта

src/realmemory/
├── encoding/     # embedders, SDR encoding
├── core/         # L1 SDRVotingIndex, L2 AssemblyNetwork, plasticity
├── policies/     # novelty gate, trace decay/promotion
├── store/        # SQLite storage (traces, edges, eligibility, events)
├── api/          # MCP server
└── eval/         # benchmarks

Лицензия

MIT