Как я построил систему постоянной памяти, которая заставляет Claude Code и Codex CLI помнить всё между сессиями.
11 вечера, вторник. Ты три часа провёл в сессии Claude Code, рефакторя платёжный сервис. Claude отлично понимает твою архитектуру — repository pattern, цепочку middleware, конвенции именования, на которые вы сошлись две недели назад. Жмёшь /compact последний раз, упираешься в лимит контекста, закрываешь терминал.
Среда, утро. Новая сессия. Новый Claude. Он ничего не знает.
«Какая у тебя структура проекта?» — спрашивает он. Снова.
Ты объясняешь архитектуру. Снова. Поправляешь ту же ошибку, которую он сделал в прошлый четверг — использовал map[string]interface{} вместо типизированных DTO. Снова. Вставляешь тот же документ с конвенциями. Снова.
Если знакомо — ты не один. Я провёл два месяца в этом цикле на 72 проектах, прежде чем решил это починить.
Настоящая проблема: stateless by design
Claude Code и OpenAI Codex CLI — выдающиеся инструменты. Но у них есть фундаментальное ограничение: ноль постоянной памяти между сессиями. Каждый разговор начинается с нуля.
Это не баг — это архитектура. Эти инструменты stateless by design. Но для любого, кто делает серьёзную, длительную разработку, statelessness — убийца продуктивности.
Вот что ты теряешь каждый раз, когда сессия заканчивается:
- Архитектурные решения и причины, по которым они приняты
- Решения багов, которые ты уже решил
- Конвенции проекта, на которые ушли часы сессий
- Ошибки, которые делал Claude (и поправки, которые ты дал)
- Ментальную модель всего твоего кодбейза
Я устал быть человеческим memory bank для своего AI-ассистента. И построил total-agent-memory — open-source MCP-сервер, дающий Claude Code (и Codex CLI, Cursor, Cline, Continue, Aider, Windsurf, Gemini CLI, OpenCode — всему, что говорит по MCP) постоянный мозг.
Сайт: totalmemory.dev · GitHub: vbcherepanov/total-agent-memory
💡 Update (май 2026): Изначально проект назывался
claude-total-memory, в v12.0.0 переименован в total-agent-memory — он работает с любым MCP-клиентом, не только с Claude Code. Старое имяclaude-total-memoryна PyPI остаётся как deprecation shim (тянет за собойtotal-agent-memory>=12.0.0), поэтому существующие установки продолжают работать.
Что он делает
total-agent-memory — это Python MCP-сервер, который сидит рядом с Claude Code. Он предоставляет 32 инструмента в 6 категориях, позволяющих Claude сохранять, искать, связывать и учиться на знаниях, которые остаются навсегда.
Думай об этом как об апгрейде Claude — с гениального коллеги с амнезией до того, кто ведёт подробный инженерный блокнот.
До и после
До (каждое утро понедельника):
Ты: Продолжаем работу над платёжным сервисом
Claude: С удовольствием помогу! Расскажи, пожалуйста, про
структуру проекта, конвенции и что мы уже сделали?
Ты: *вздыхаешь, вставляешь 2000 токенов контекста*После:
Ты: Продолжаем работу над платёжным сервисом
Claude: [memory_recall("payment service architecture")]
Понял. В прошлой сессии мы рефакторили PaymentService под
gateway-паттерн. Интеграция с Тинькоф готова, дальше Stripe.
Ты предпочитаешь constructor injection и метрики-middleware,
который мы настроили в internal/middleware/metrics.go.
Подхватываю с того места, где остановились.В этом разница. Никакого переобъяснения. Никакой вставки контекста. Claude просто знает.
32 инструмента в 6 категориях
1. Core Memory (12 инструментов)
Фундамент. Сохранение и поиск знаний с пятью типами: decision, solution, lesson, fact и convention.
# Claude сохраняет решение в процессе сессии
memory_save(
content="Использовать UUID v7 для всех первичных ключей вместо SERIAL.
Причины: сортируются по времени, нет contention'а на sequence,
лучше для распределённых систем.",
type="decision",
tags=["database", "postgresql", "architecture"],
project="payment-service"
)# Через неделю, в другой сессии, Claude ищет
memory_recall(
query="primary key strategy for postgresql",
detail="full"
)
# Возвращает: ровно то решение выше, отранжированное по релевантностиПоиск — не просто keyword matching. Это 4-уровневый гибридный пайплайн:
Запрос: "docker networking between services"
│
├── Уровень 1: FTS5 + BM25 keyword search
│ └── Находит точные совпадения: "docker", "networking"
│
├── Уровень 2: Semantic search (ChromaDB vectors)
│ └── Находит связанное: "container communication", "bridge network"
│
├── Уровень 3: Fuzzy matching (SequenceMatcher)
│ └── Ловит опечатки: "dokcer netowrking" всё равно работает
│
└── Уровень 4: Graph expansion
└── Идёт по связям: docker networking → compose config → env variables
Все уровни сливаются через Reciprocal Rank Fusion (RRF)Это важно. Один BM25 даёт 89% на retrieval-бенчмарках. Один semantic search — 91%. Полный 4-уровневый пайплайн с RRF-фьюжном? 97.45% на LongMemEval R@5 — выше, чем 96.6% у MemPalace.
2. Self-Improvement (6 инструментов) — главная фича
Здесь становится интересно. Claude не просто хранит знания — он учится на собственных ошибках.
Вот пайплайн:
Сессия 1: Claude использует `npm install` внутри Docker
→ Хук ловит ошибку
→ self_error_log(category="docker", error="running npm outside container")
Сессия 3: Та же ошибка снова
→ Счётчик ошибок в категории "docker": 2
Сессия 5: Третий раз
→ 3+ ошибки в одной категории триггерит auto-insight
→ self_insight("Always run package managers inside Docker containers")
Insight набирает уверенность через успешные применения...
→ Промоут до SOUL rule (importance >= 5, confidence >= 0.8)
→ Правило загружается на КАЖДОМ старте сессии
→ Claude больше никогда не делает эту ошибкуИнструменты: self_error_log, self_insight, self_rules, self_patterns, self_reflect, self_rules_context.
Концепция SOUL rules — постоянных правил поведения, формирующих то, как Claude работает, — это то, что превращает систему из базы данных в нечто большее. Это feedback loop. Claude буквально становится лучше работать с твоим кодбейзом со временем.
3. Knowledge Graph (4 инструмента)
Знание не плоское. Решения связаны с другими решениями. Решения багов ссылаются на проблемы, которые они закрыли. Граф фиксирует эти связи.
memory_relate(
from_id=42, # "Use gateway pattern for payments"
to_id=67, # "Tinkoff API requires idempotency keys"
relation="context"
)Когда Claude вспоминает решение про gateway-паттерн, он автоматически подтягивает связанный контекст про требования API Тинькофф. Никакой ручной линковки после первоначальной связи.
4. Episodic Memory (2 инструмента)
Факты говорят что. Эпизоды говорят что произошло.
memory_episode_save(
content="Потратил 3 часа, дебажа race condition в order
service. Корневая причина: общий пул соединений к БД
между горутинами без правильной отмены контекста.
Починил per-request connection checkout.",
context="payment-service sprint 4"
)Когда Claude через несколько месяцев натыкается на похожую concurrency-проблему, он не просто знает фикс — он помнит сам процесс отладки и тупиковые попытки.
5. Skills & Competencies (3 инструмента)
Claude отслеживает, в чём он хорош, а где буксует.
memory_skill_get(skill="kubernetes-debugging")
# Возвращает: уровень владения, последняя практика, траектория улучшения
memory_self_assess()
# Возвращает: сильные стороны, слабые, слепые пятна по истории ошибок6. Advanced Cognitive Tools (5 инструментов)
Spreading activation (memory_associate), автоматическая сборка контекста (memory_context_build), логирование наблюдений (memory_observe) и on-demand рефлексия (memory_reflect_now).
Техническая архитектура
Под капотом — намеренно просто:
┌─────────────────────────────────────────────┐
│ MCP Server (Python). │
│ │
│ ┌──────────┐ ┌───────────┐ ┌──────────┐ │
│ │ SQLite │ │ ChromaDB │ │ Graph │ │
│ │ FTS5 │ │ (vectors) │ │ Engine │ │
│ │ + BM25 │ │ │ │ │ │
│ └──────────┘ └───────────┘ └──────────┘ │
│ │
│ ┌──────────────────────────────────────┐ │
│ │ Privacy Layer (auto-redacts secrets) │ │
│ └──────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────┐ │
│ │ Web Dashboard (localhost:37737) │ │
│ └──────────────────────────────────────┘ │
└─────────────────────────────────────────────┘Ключевые архитектурные решения:
- SQLite FTS5 для keyword-поиска с правильным BM25-ранжированием — внешний поисковый движок не нужен
- ChromaDB для vector similarity с binary quantization для скорости
- Decay scoring с 90-дневным half-life — свежее знание ранжируется выше, но ничего не выкидывается раньше времени
- Retention zones: active (по умолчанию) → archived (180 дней, не возвращается в recall) → purged (365 дней в архиве)
- Auto-deduplication через Jaccard similarity (порог >0.85) — предотвращает раздувание знаний
- Privacy stripping автоматически вычищает API-ключи, JWT и email-адреса перед сохранением
- Ноль внешних сервисов — всё работает локально. Знание о твоём коде никогда не покидает твою машину.
Работает с Claude Code И Codex CLI
Так как это MCP-сервер, любой инструмент, говорящий по протоколу MCP, может его использовать. Настраиваешь один раз — и Claude Code, и OpenAI Codex CLI делят одну и ту же базу памяти. Переключаешься между инструментами без потери контекста.
Реальные цифры за 2+ месяца ежедневного использования
Это не weekend-проект, про который я теоретизирую. Он крутится у меня на машине в ежедневном продакшене больше двух месяцев:
| Метрика | Значение |
|---|---|
| Активных записей знаний | 1 683 |
| Отслеживаемых проектов | 72 |
| Узлов графа | 1 847 |
| Рёбер графа | 20 925 |
| Выученных навыков | 177 |
| Зафиксированных эпизодов | 164 |
Субъективная разница — драматическая. Утро понедельника превратилось из 15–20 минут восстановления контекста в практически ноль. Claude подхватывает ровно с того места, где остановился, — не потому что сессия сохранилась, а потому что каждый важный кусок контекста был сохранён и моментально находится.
Self-improvement loop на практике
Вот реальный сценарий.
Неделя 1: я работаю над Go-проектом. Claude генерирует хендлер с 30 строками бизнес-логики внутри. Я поправляю — «хендлеры должны быть тонкими, до 15 строк, делегировать в сервисный слой». Claude правит. Поправка сохраняется как convention.
Неделя 2: другой проект, тот же стек. Claude снова генерит толстый хендлер. Хук ловит мою поправку, логирует через self_error_log. Это ошибка #2 в категории «go-architecture».
Неделя 3: повторяется снова. Ошибка #3. Система ловит паттерн и генерирует insight: «Go-хендлеры должны быть тонкими (до 15 строк) — вся бизнес-логика в сервисном слое».
После нескольких успешных применений insight промоутится до SOUL rule. Теперь каждая новая сессия стартует с тем, что Claude знает это правило. Толстые хендлеры перестают появляться. Не потому что я напомнил — потому что он научился.
Это разница между инструментом, хранящим текст, и тем, который реально улучшается.
Как начать
Выбери что подходит твоему стеку — все шесть путей установки приводят к одному и тому же MCP-серверу. Полные инструкции на totalmemory.dev.
# Node (zero-install через npx)
npx -y total-agent-memory connect claude-code
# Python через uv (быстро)
uvx total-agent-memory
# Python через pipx (изолированный venv)
pipx install total-agent-memory
# Homebrew (macOS / Linuxbrew)
brew install vbcherepanov/tap/total-memory
# Docker (multi-arch)
docker run --rm -p 37737:37737 -v ~/.tam:/data ghcr.io/vbcherepanov/total-agent-memory:latest
# Ручной clone
git clone https://github.com/vbcherepanov/total-agent-memory.git ~/total-agent-memory && cd ~/total-agent-memory && ./install.shПуть через npx также прописывает MCP entry в выбранную IDE — connect claude-code, connect codex, connect cursor, connect cline, connect continue, connect aider, connect windsurf, connect gemini-cli, connect opencode.
Если предпочитаешь вручную — добавь в ~/.claude/settings.json:
{
"mcpServers": {
"memory": {
"command": "/absolute/path/to/.venv/bin/total-agent-memory",
"env": {
"TAM_MEMORY_DIR": "~/.tam"
}
}
}
}Готово. На следующем старте Claude Code у него будет 32 новых инструмента. Начни с memory_save и memory_recall — остальное вырастет оттуда.
Ограничения (честный взгляд)
Идеальных проектов не бывает. Что нужно знать:
- Холодный старт первой сессии: память изначально пуста. Нужно 2–3 сессии активного использования, прежде чем эффект накапливается.
- Хранилище растёт: 1 600+ записей занимают около 50 МБ с векторами. На современной машине не критично, но и не ноль.
- Claude нужно подталкивать вначале: пока SOUL rules не накопились, может потребоваться напомнить ему вызвать
memory_recallв начале сессии. Хуки помогают это автоматизировать. - Зависимость от Python: серверу нужен Python 3.10+ и несколько пакетов. Install-скрипт это разруливает, но это не один бинарь.
Почему open source
Я строил это для себя. Потом понял, что у каждого пользователя Claude Code та же проблема. Проект под MIT-лицензией — используй, форкай, модифицируй, контрибьють.
Проблема памяти — это, пожалуй, самая большая точка трения в AI-разработке сегодня. Контекстные окна растут, но никогда не станут бесконечными. И даже если бы стали, перезагружать контекст каждую сессию — расточительно. Постоянная память — правильная абстракция.
Попробуй
Если ты используешь Claude Code или Codex CLI для реальной работы — не для демо, не для игрушечных проектов, а для настоящей продолжающейся разработки — это изменит твой workflow.
Поставь звезду репозиторию, попробуй неделю и почувствуй разницу, когда твой AI-ассистент реально помнит, кто ты и что ты строишь.
Сайт: totalmemory.dev · GitHub: vbcherepanov/total-agent-memory
Лицензия: MIT — бесплатно навсегда.
Vitalii Cherepanov — software engineer, строящий инструменты на стыке AI и продуктивности разработчиков. Пишет на Go и PHP днём и учит Claude помнить вещи ночью.