По умолчанию весь каталог лежит в ~/.memory. Его можно заменить переменной MEMORY_HOME или постоянной настройкой memory config set-home.

Почему Markdown - неплохая основа

Каждый файл сессии - обычный документ Markdown с метаданными в YAML. Это значит, что память не заперта внутри закрытой базы: её можно читать, искать, править, версионировать в Git или открыть как хранилище Obsidian.

Условно запись содержит такие поля:

Важное отличие от просто папки с заметками: Markdown здесь удобная человеку форма хранения, но параллельно EchoVault ведёт индекс, метаданные, векторы, состояние архива, замещения и статистику обращений.

Зачем тогда ещё SQLite

Читать десятки или сотни файлов на каждый запрос неудобно, поэтому рядом живёт локальный индекс. В текущем коде там таблица записей с идентификаторами и метаданными, отдельные подробности, виртуальная таблица полнотекстового поиска FTS5, таблица sqlite-vec, если включены эмбеддинги, статус "активна или в архиве", ссылка на запись-замену, уверенность, сроки действия, коммит, ветка и связи, а также локальные счётчики использования результатов.

То есть Markdown делает память переносимой и обозримой, а SQLite - достаточно быстрой для агента.

Интерфейс намеренно очень маленький

Это удачное решение. Вместо двадцати инструментов агенту нужно понять три глагола: загрузить контекст, поискать глубже, сохранить новое. Причём сами описания инструментов содержат указания агенту: не сохранять опечатки и очевидности, а писать память для будущего агента, у которого нулевой контекст.

Установка

На macOS и Linux README предлагает установщик:

Он предпочитает uv или pipx, а если их нет - создаёт отдельное виртуальное окружение в ~/.local/share/echovault. Системный Python установщик не трогает.

Ручной вариант:

Одна ловушка, о которой README предупреждает отдельно: не делайте просто pip install echovault - это имя на PyPI занято другим проектом. Ставьте по полному адресу из Git.

Подключение агентов и общая память

Интеграцию можно поставить только в текущий проект:

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

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

Первая нормальная память

Каждое поле здесь работает. Заголовок - короткое имя для поиска и набора контекста. "Что" - что реально изменилось или было обнаружено. "Почему" - причина решения, и через месяц именно она часто важнее результата. "Последствия" - что теперь обязан учитывать будущий агент. Связанные файлы привязывают память к участкам кода, а источник показывает, какой агент создал запись.

Подробности лучше оформлять по схеме: контекст, рассмотренные варианты, решение, компромиссы, что осталось сделать. Так заметка превращается в маленький документ об архитектурном решении.

Десять категорий памяти

Живая память и происхождение записи

В версии 0.5.0 EchoVault перестал считать любую старую запись одинаково полезной. У памяти появились поля, позволяющие понять, насколько ей доверять, когда она была актуальна, в какой ветке и коммите появилась, когда её последний раз проверяли, какие другие записи она замещает или связывает и остались ли незакрытые продолжения.

Идея простая: долгосрочная память без жизненного цикла со временем становится кладбищем старых решений. Живая память хранит не только что было сказано, но и можно ли этому всё ещё верить. На практике это выглядит так:

Для памяти о коде это особенно ценно: "когда-то работало" и "проверено на текущем main вчера" - совершенно разные уровни доверия.

Playbook: память, которую можно выполнить

Обычная запись сообщает факт. Playbook хранит процедуру:

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

Набор контекста, бюджет токенов и как его отключить

EchoVault собирает контекст под конкретный запрос, а не отдаёт последние десять записей. В описании инструмента агенту прямо предлагается вызывать его перед разработкой фичи, планированием, отладкой и работой над архитектурой. В ответ может войти релевантные решения, ограничения, состояние проекта, незавершённая работа, известные исправления, playbooks, происхождение записей и примерная стоимость контекста в токенах.

Самое интересное - как ограничивается объём:

Вместо идеи "всегда возвращать двадцать записей" система работает с приблизительным бюджетом контекста. Сначала в него попадают самые релевантные результаты, затем ограничения, состояние проекта, незавершённая работа, известные исправления, playbooks, решения и полезные свежие записи. Смысл практический: цель системы памяти не показать агенту как можно больше прошлого, а дать максимум полезного за ограниченное число токенов.

Автоматическую подстановку контекста можно выключить, не отключая память. Политика работает на трёх уровнях: переменная MEMORY_CONTEXT для текущего процесса, настройка конкретного агента и общий режим в конфигурации.

Поиск и сохранение при этом продолжают работать: проактивную подстановку убрали, а память осталась доступной по явному запросу.

Поиск: сначала слова, векторы - когда нужно

Если эмбеддинги настроены, EchoVault объединяет полнотекстовый поиск FTS5 и векторную близость через sqlite-vec. В текущем коде стандартное слияние использует веса 0.3 для полнотекстовой части и 0.7 для векторной, а при определённых расхождениях между единственным словесным попаданием и сильным смысловым векторный вес может подниматься ещё выше. Заодно временные диагностические и тестовые записи понижаются в выдаче, если запрос не спрашивает именно о них.

Но эмбеддинги не вызываются без нужды - конвейер построен по принципу "сначала полнотекстовый поиск":

Это снижает задержку и особенно полезно с удалённым API эмбеддингов: поиск по точному имени функции или технологии часто завершается локально.

Есть и второй способ экономии - на глубине результата. README описывает результаты поиска как компактные указатели: короткая выжимка порядка десятков токенов плюс идентификатор и отметка, что подробности доступны.

Получается двухэтапный поиск: сначала дёшево выбрать нужные записи, а большое тело читать только для действительно важной.

Ollama или OpenAI, локальный контур и обогащение

Облачный вариант:

Поставщик в стиле OpenAI позволяет указать свой адрес - например, для локального vLLM или совместимого шлюза. После смены модели эмбеддингов индекс надо перестроить:

Полностью локально и бесплатно - можно. Схема выглядит так:

При поставщике ollama эмбеддинги остаются локальными, и если обогащение выключено или использует локальную точку доступа, EchoVault ничего не отправляет наружу. Но local-first не означает автоматически local-only: выбрав поставщика OpenAI, вы отправляете текст, для которого строится эмбеддинг или обогащение, внешнему API.

Само обогащение - необязательный шаг с участием модели перед сохранением: он может улучшить выжимку или добавить теги.

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

Три слоя защиты секретов

Перед записью работает конвейер затирания: явные пометки <redacted>...</redacted>, регулярные выражения для известных форматов секретов и ваши правила проекта из .memoryignore.

В текущем коде есть шаблоны для ключей Stripe, персональных токенов GitHub, идентификаторов доступа AWS, ботовых токенов Slack, заголовков приватных ключей, JWT и полей вида password, secret, api_key. Если в тексте памяти было:

на диск попадёт:

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

Obsidian и терминальный дашборд

Поскольку файлы сессий - валидный Markdown, ничто не мешает открыть ~/.memory/vault/ в Obsidian или любом другом редакторе. Это удобно для ручного аудита: вы буквально видите, что агент считает важной долговременной памятью, а не просматриваете непрозрачные векторные записи. Если Markdown правили руками, есть команды импорта и переиндексации, чтобы синхронизировать поисковый слой.

Начиная с версии 0.4.0 дашборд переписан на Rust с ratatui и crossterm: он запускается отдельным бинарником примерно на три мегабайта, стартует мгновенно и не требует Python-окружения для интерфейса. Из него можно искать и фильтровать записи, смотреть подробности, открывать запись в $EDITOR как YAML-файл, архивировать и восстанавливать, просматривать кандидатов на дубликаты и объединять их, видеть статистику. Поиск дубликатов вынесен в фоновый поток, поэтому интерфейс не подвисает на квадратичном сравнении. А вот импорт и переиндексация внутри дашборда не выполняются - он лишь подсказывает соответствующие команды memory import и memory reindex.

Навигация сделана в духе k9s: цифры от одного до четырёх переключают панели, j, k, g и G двигают курсор по-вимовски, косая черта открывает поиск, двоеточие - палитру команд, вопросительный знак - подсказку.

Качество поиска предлагается измерять

Это редкая для memory-проектов черта. Вместо "у нас смысловой поиск, значит всё хорошо" EchoVault позволяет собрать набор реальных вопросов с ожидаемыми ответами:

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

Отсюда же вырастает предупреждение, которое стоит запомнить: нельзя просто выставить похожесть 0.8. У разных моделей эмбеддингов распределения похожести совершенно разные, и README приводит убедительный пример - на их эталонном наборе с моделью nomic-embed-text релевантные значения оказались примерно в диапазоне 0.05-0.07, поэтому порог 0.55 отбрасывал бы все смысловые кандидаты. Именно поэтому в конфигурации два разных параметра: min_relevance отвечает за итоговое качество ранжированного результата, а min_vector_similarity - за нижнюю границу именно векторного кандидата. Числа калибровки не стоит копировать слепо: сам README советует повторять калибровку для каждой модели и своего хранилища.

Обратная связь, ревизия и доктор

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

Отдельно есть проверка здоровья:

Она смотрит состояние хранилища и индекса, векторы, ссылки, проблемы жизненного цикла, рост, задержку и рискованные настройки. Это зрелая мысль: долгосрочная память - это инфраструктура. Если индекс отстал от Markdown, эмбеддинги построены старой моделью или ссылки ведут на архивные записи, качество ответов падает даже при превосходной модели.

Ограничения и настоящие компромиссы

Главная специализация - агенты, работающие с кодом. Структура записей, определение проекта, связанные файлы, происхождение из Git и playbooks явно рассчитаны на разработку; для персонального ассистента модель в духе Mem0 или Memanto будет естественнее.

Markdown и индекс надо держать согласованными. Человек может править файлы руками - это плюс к обозримости, но именно поэтому импорт, переиндексация и проверка здоровья имеют реальную ценность.

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

Локальный поиск не означает, что локален сам агент. EchoVault может целиком хранить и индексировать память у вас, но у Claude Code или Codex своя модельная инфраструктура - это отдельный вопрос приватности.

И наконец, система быстро развивается: в основной ветке уже есть неопубликованные изменения установщика и настройки, поэтому для воспроизводимого окружения лучше фиксировать тег выпуска, а не ставить всегда из main.

Среди других проектов, и когда это ваш выбор

Самое отличительное здесь - сочетание простой файловой основы с довольно серьёзной инженерией вокруг качества поиска и жизненного цикла записей.

EchoVault особенно хорош, если вы постоянно работаете с Claude Code, Codex или Cursor на одних и тех же проектах; не хотите отдавать решения по проекту отдельному облачному сервису; хотите видеть память обычными Markdown-файлами; вам нужен локальный смысловой поиск через Ollama; важны playbooks и известные исправления, а не только факты о пользователе; хочется измерять качество поиска на собственных реальных задачах; одна память должна работать сразу с несколькими агентами; не хочется держать постоянно запущенный демон.

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

Начинался проект с простой идеи - сохранить решения агента локально. Версия 0.5.0 делает её заметно интереснее: это уже не папка Markdown с векторным поиском, а маленькая система эксплуатации памяти. Память остаётся читаемой, а не непрозрачной базой. Поиск быстрый: сначала слова, векторы только когда помогают. Контекст избирательный: ограничен релевантностью и бюджетом токенов. И память обслуживаемая: есть измерение, обратная связь, ревизия, проверка здоровья и происхождение записей. Главная мысль проекта в том, что память агента должна быть не просто постоянной - она должна быть локальной, читаемой, измеримой и обслуживаемой, иначе через несколько месяцев долгосрочная память превращается в долговременный мусор.

Источники

Статья сверена 9 августа 2026 года с актуальной основной ветвью, выпуском v0.5.0, README, журналом изменений и кодом MCP-сервера, поиска, базы данных и затирания секретов. В основной ветви уже есть отдельные неопубликованные изменения установщика, поэтому производственную установку разумно фиксировать на теге выпуска. Дополнена 14 августа 2026 года по свежему клону: из возможностей дашборда убраны импорт и переиндексация, которых он не выполняет, добавлены размер бинарника, фоновый поиск дубликатов и раскладка клавиш.

• GitHub: mraza007/echovault
• README.md
• CHANGELOG.md
• Release v0.5.0
• pyproject.toml
• Реализация MCP-сервера
• Реализация гибридного поиска
• Слой SQLite / FTS5 / sqlite-vec
• Модель данных памяти
• Конвейер затирания секретов
• MIT License