MemPalace: развертывание и практическое применение — создаём систему ИИ‑памяти, которую невозможно забыть

Средняя сложность · около 20 минут · Вы освоите полный цикл развертывания MemPalace, поймёте иерархическую структуру Palace и научитесь подключать систему памяти к любому ИИ через MCP.

---

Целевая аудитория

1–3 года опыта разработки: вы уже использовали инструменты ИИ для программирования вроде Claude Code / Cursor / Copilot. Вам хочется, чтобы ИИ в долгих проектах сохранял контекстную память и больше не начинал каждый раз с нуля.

---

Ключевые зависимости и окружение

• Python: 3.9+
• Основные зависимости: chromadb>=0.5.0,<0.7, pyyaml>=6.0
• Способ установки: pip install mempalace или uv pip install mempalace
• Операционная система: macOS / Linux / Windows (WSL тоже подходит)
• Хранение: ChromaDB (векторная база) + SQLite (граф знаний) — всё локально, без сети

---

Полная структура проекта

mempalace/
├── mempalace/                 # ядро: основной Python‑пакет
│   ├── cli.py                 # точка входа CLI, маршрутизирует mine/search/init и т.п.
│   ├── mcp_server.py          # MCP‑сервер, предоставляет 19 инструментов
│   ├── knowledge_graph.py     # темпоральный граф знаний (SQLite)
│   ├── palace_graph.py        # навигационный граф Palace (обход BFS, поиск туннелей)
│   ├── convo_miner.py         # добыча из диалогов: разбиение по Q+A
│   ├── miner.py               # добыча из файлов проекта: разбиение по абзацам
│   ├── searcher.py            # семантический поиск (ChromaDB)
│   ├── normalize.py           # нормализация 5 форматов диалогов
│   ├── dialect.py             # AAAK‑сжатый диалект
│   ├── layers.py              # четырёхуровневый стек памяти (L0–L3)
│   ├── onboarding.py          # инициализация/онбординг
│   ├── entity_detector.py     # автоопределение имён/названий проектов
│   └── split_mega_files.py    # разбиение и склейка файлов сессий
├── hooks/                     # хуки для автоматического сохранения в Claude Code
│   ├── mempal_save_hook.sh     # сохранять каждые 15 сообщений
│   └── mempal_precompact_hook.sh  # срочное сохранение перед сжатием контекста
├── benchmarks/               # воспроизводимые бенчмарки (LongMemEval / LoCoMo)
│   ├── longmemeval_bench.py
│   ├── locomo_bench.py
│   └── BENCHMARKS.md
└── examples/
    ├── basic_mining.py
    └── mcp_setup.md

---

Пошагово

Step 1: Установка

pip install mempalace

Минимальная версия Python — 3.9. После установки проверьте доступность:

mempalace --version

---

Step 2: Инициализация дворца памяти

mempalace init ~/projects/myapp

Команда init запускает сценарий онбординга и последовательно спрашивает:

• людей, с кем вы часто сотрудничаете (добавьте их в wing‑настройки)
• проект, над которым вы работаете (для каждого проекта — свой wing)
• вашу AI‑идентичность (записывается в слой L0)

После завершения онбординга будет создано два файла конфигурации:

• ~/.mempalace/config.json — глобальная конфигурация (путь до palace и т.п.)
• ~/.mempalace/wing_config.json — wing‑настройки и соответствия ключевых слов

Сгенерированный wing_config.json примерно такой:

{
  "default_wing": "wing_general",
  "wings": {
    "wing_kai": { "type": "person", "keywords": ["kai", "kai's"] },
    "wing_driftwood": { "type": "project", "keywords": ["driftwood", "analytics", "saas"] }
  }
}

Каждый раз при запуске ИИ нужно загрузить только L0 + L1 (примерно 170 токенов) — и он уже понимает, как устроен ваш мир.

---

Step 3: Добыча данных

MemPalace поддерживает два режима добычи — выберите подходящий под ваш источник данных.

Режим A: добыча из файлов проекта (код, документация, заметки)

mempalace mine ~/projects/myapp

miner рекурсивно сканирует директорию, разбивает по абзацам, сохраняет в ChromaDB, а Drawer хранит исходный контент.

Режим B: добыча из экспортированных диалогов (Claude/ChatGPT/Slack)

# базовое использование
mempalace mine ~/chats/ --mode convos

# указать wing — так удобнее фильтровать по проекту позже
mempalace mine ~/chats/ --mode convos --wing myapp

# включить автоматическую классификацию (извлечение решений, предпочтений, вех, вопросов и контекстов эмоций)
mempalace mine ~/chats/ --mode convos --extract general

convo_miner разбивает диалоги по Q+A, автоматически определяя принадлежность room (через сопоставление 70+ режимов из room_detector_local.py; внешние API не нужны).

---

Step 4: Проверка семантическим поиском

После добычи попробуйте поиск:

mempalace search "why did we switch to GraphQL"

Добавьте фильтр по wing — ищите только в конкретном проекте:

mempalace search "auth decision" --wing driftwood

Ещё точнее — добавьте фильтр по room:

mempalace search "auth decision" --wing driftwood --room auth-migration

Возвращается исходный текст из Drawer (verbatim), без резюме и без потери информации. ChromaDB выполняет векторный поиск, а Closet — структурированное резюме.

---

Step 5: Подключение MCP‑сервиса

MCP (Model Context Protocol) позволяет выставить MemPalace как инструмент для любого ИИ. Один раз настроили — и работает постоянно.

Подключение к Claude Code:

claude mcp add mempalace -- python -m mempalace.mcp_server

После настройки Claude Code автоматически получает 19 инструментов: ИИ будет вызывать mempalace_search сам, когда это потребуется — вам не нужно вручную искать.

Подключение к Gemini CLI:

# смотрите examples/gemini_cli_setup.md
claude mcp add mempalace -- python -m mempalace.mcp_server

Gemini CLI лучше поддерживает MCP; также можно автоматически настроить save hooks.

Список MCP‑инструментов (19 штук):

Из ответа mempalace_status ИИ автоматически учит синтаксис AAAK и протокол памяти — без вашего ручного промпта.

---

Step 6: Настройка Auto‑Save Hooks для Claude Code

Hooks в Claude Code позволяют MemPalace автоматически сохранять память в процессе каждой беседы.

Измените ~/.claude/settings.json (глобальная конфигурация Claude Code) и добавьте:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/mempalace/hooks/mempal_save_hook.sh"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/mempalace/hooks/mempal_precompact_hook.sh"
          }
        ]
      }
    ]
  }
}

Разница двух хуков:

• Stop: срабатывает раз в 15 сообщений; выполняется структурированное сохранение — фиксируются тема, решения, цитаты и изменения кода, а также пересобирается слой L1 (ключевые факты).
• PreCompact: срабатывает перед сжатием контекста; делает аварийное сохранение ещё не сохранённой памяти, чтобы при сжатии не потерялся важный контекст.

---

Step 7: Понимание структуры Palace

Главная абстракция MemPalace — «дворец памяти»: это отсылка к технике запоминания древнегреческих ораторов, где пространственная структура заменяет плоский поисковый индекс.

  WING: kai (person)

    ┌──────────┐  ──hall──  ┌──────────┐
    │ auth-mig │            │ security  │
    └────┬─────┘            └──────────┘
         │
         ▼
    ┌──────────┐      ┌──────────┐
    │  Closet  │ ───▶ │  Drawer  │  ← исходный текст находится здесь
    └──────────┘      └──────────┘

  TUNNEL (связь между wing):
  kai/auth-mig  ←→  driftwood/auth-mig  ←→  priya/auth-mig

Wings: один человек или один проект — основная категория памяти. В каждом wing может быть несколько rooms.

Rooms: конкретные темы внутри wing, например auth-migration, ci-pipeline, pricing. При совпадении имени room в разных wing автоматически создаются туннели.

Halls: коридоры памяти по типам; в каждом wing набор hall один и тот же:

• hall_facts — зафиксированные решения
• hall_events — сессии, вехи, процесс отладки
• hall_discoveries — прорывы и новые инсайты
• hall_preferences — привычки, предпочтения, мнения
• hall_advice — рекомендации и решения

Closets: слой резюме — указывает на место, где находится исходный контент (Drawer). Исходный текст не теряется: добавляется лишь навигационная структура.

Drawers: место, где хранится исходный текст. Режим raw verbatim в MemPalace как раз читает оригинал отсюда для векторного поиска — так и достигается 96.6% R@5.

---

Step 8: Темпоральные связи при использовании Knowledge Graph

ChromaDB хранит векторы исходного текста, а Knowledge Graph (SQLite) — структурированные факт‑триулы; они дополняют друг друга.

from mempalace.knowledge_graph import KnowledgeGraph

kg = KnowledgeGraph()

# Добавляем факты с периодом действия
kg.add_triple("Kai", "works_on", "Orion", valid_from="2025-06-01")
kg.add_triple("Maya", "assigned_to", "auth-migration", valid_from="2026-01-15")
kg.add_triple("Maya", "completed", "auth-migration", valid_from="2026-02-01")

# Что делает Kai сейчас
print(kg.query_entity("Kai"))
# → [Kai → works_on → Orion (current)]

# Как обстояло дело на 2026-01-20 (в это время Maya ещё не завершила auth-migration)
print(kg.query_entity("Maya", as_of="2026-01-20"))
# → [Maya → assigned_to → auth-migration]

# Посмотреть таймлайн проекта Orion
print(kg.timeline("Orion"))
# → цепочка фактов в хронологическом порядке

# Maya сменила проект — старый факт становится недействительным
kg.invalidate("Maya", "assigned_to", "auth-migration", ended="2026-02-01")
# Теперь query_entity("Maya") больше не возвращает auth-migration

Окна валидности фактов (valid_from / ended) — ключевая возможность MemPalace: при запросе истории вы получаете «что произошло тогда», а не «что происходит сейчас».

---

Step 9: Четырёхслойная архитектура стека памяти

Стратегия поиска MemPalace устроена в четыре слоя: чем выше — тем легче, чем ниже — тем точнее:

При каждом запуске ИИ сначала загружается L0 + L1 (mempalace wake-up) — за 170 токенов формируется полноценный контекст‑фон. L2 подключается только когда тема затрагивает конкретный room; L3 с полным поиском по ChromaDB запускается только при явных вопросах.

Это и объясняет, почему у MemPalace очень низкая стоимость — $10/год на расходы по поиску против $507/год в варианте с резюмированием.

---

Частые проблемы и их устранение

Q1: Пустые результаты поиска, хотя вы уверены, что контент существует

Проверьте в три шага:

# 1. Убедитесь, что названия wing и room указаны верно
mempalace list-wings
mempalace list-rooms --wing myapp

# 2. Расширьте область поиска: не задавайте конкретные wing/room
mempalace search "ключевое слово"   # без --wing

# 3. Проверьте, действительно ли данные записались в ChromaDB
mempalace status            # посмотрите, не равен ли drawer‑счётчик 0

Если mempalace status показывает 0 drawer, значит шаг добычи прошёл неуспешно: возможно, формат файлов диалогов сейчас не поддерживается (на данный момент поддерживаются Claude Code JSONL, Claude.ai JSON, ChatGPT JSON, Slack JSON, plain text).

Q2: Конфликт имён коллекций в ChromaDB

По умолчанию имя коллекции — mempalace_drawers. При нескольких запусках init или работе в разных директориях возможны конфликты. В ~/.mempalace/config.json явно задайте путь:

{
  "palace_path": "/custom/path/to/palace",
  "collection_name": "mempalace_drawers"
}

Затем перекройте через --palace <path>:

mempalace search "query" --palace /custom/path/to/palace

Q3: Не удалось подключиться по MCP

Сначала вручную проверьте, что MCP‑сервис стартует корректно:

python -m mempalace.mcp_server
# в норме не должно выводиться ничего; держите процесс в активном состоянии
# Ctrl+C — выход

Если ошибка ModuleNotFoundError, проверьте корректность установки:

pip show mempalace

Если используете виртуальное окружение, убедитесь, что в MCP‑конфигурации Claude Code указан верный Python‑путь:

which python   # получить корректный путь к python
claude mcp add mempalace -- /path/to/python -m mempalace.mcp_server

Q4: Вызов MCP инструментов работает, но результат не соответствует ожиданиям

Когда ИИ вызывает mempalace_search, параметры wing/room должны совпадать максимально точно, чтобы структура Palace раскрыла свой максимум. В prompt направьте ИИ использовать правильные фильтры:

When searching for project-specific memories, always pass --wing <project>.
When searching for a specific topic, always pass --room <room-name>.

Q5: Hook‑скрипт не срабатывает

# проверить, включены ли hooks в Claude Code
claude doctor

Убедитесь, что в settings.json пути к hooks указаны как абсолютные. Относительные пути могут не распознаваться в Claude Code при работе из другого рабочего каталога.

Q6: Темпоральные запросы к графу знаний возвращают неожиданные результаты

Темпоральные запросы зависят от формата параметра as_of: дата обязательно должна быть в формате YYYY-MM-DD:

# неверный формат
kg.query_entity("Kai", as_of="2026/03/01")

# правильный формат
kg.query_entity("Kai", as_of="2026-03-01")

Также убедитесь, что при добавлении фактов через add_triple параметр valid_from был задан в корректном формате — иначе окно валидности не сработает.

---

Расширенное чтение / направления развития

Экспериментальный слой сжатия AAAK

AAAK — это сжатый вносящий потери (lossy) сокращённый диалект: повторяющиеся сущности заменяются через регулярные замены на код. В больших масштабах (когда один и тот же проект упоминается сотни раз) это снижает стоимость токенов, но на данный момент режим raw verbatim (96.6%) всё ещё превосходит AAAK‑режим (84.2%). Подходит для длительных проектов, множества сессий и ситуаций, где много повторяющихся сущностей.

Разделение памяти у Specialist Agents (мультиагентный режим)

У каждого агента — отдельный wing и AAAK‑дневник:

~/.mempalace/agents/
  ├── reviewer.json    # качество кода, паттерны, баги
  ├── architect.json   # архитектурные решения, компромиссы
  └── ops.json         # деплой, фейлы, базовая инфраструктура

ИИ во время работы в runtime динамически находит agent из palace, не нужно писать какие‑либо настройки в CLAUDE.md.

Воспроизведение бенчмарков

В каталоге benchmarks/ лежат полные скрипты для воспроизведения LongMemEval и LoCoMo:

python benchmarks/longmemeval_bench.py

Весь процесс не требует API key: на M2 Ultra все 500 вопросов выполняются примерно за 5 минут — это подтверждает воспроизводимость 96.6%.

Горизонтальное сравнение с другими системами

MemPalace — единственный вариант, который достигает максимального балла при нулевом количестве API‑вызовов.