Graphify и MemPalace: агенту нужна не «память», а карта проекта и история решений

Каждая новая сессия с coding agent начинается с небольшой амнезии.

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

Обычно это пытаются назвать одним словом: «память». Но под ним прячутся две разные задачи.

Первая — навигация. Агенту нужна карта рабочего пространства: файлы, функции, классы, SQL-схемы, Terraform, документация, связи между модулями и места, через которые проходит половина проекта. Без такой карты он тратит контекст на разведку: grep, find, чтение README, чтение package.json, переходы по импортам, случайные файлы и ещё один grep.

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

Graphify и MemPalace закрывают разные стороны этой проблемы.

Graphify даёт агенту карту кода, документов и инфраструктуры. MemPalace сохраняет историю разговоров, решений и проектных предпочтений.

Они не конкурируют. Graphify отвечает: «где это находится и с чем связано?» MemPalace отвечает: «что мы уже про это знаем и что уже решили?»

Если смешать эти вопросы, получится обычная каша из RAG, embeddings, summaries и надежды, что top-k сам всё разрулит. Обычно не разруливает.

Почему «просто RAG» плохо ложится на кодинг

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

В коде важна не только похожесть слов. Важны связи.

Вопрос «как работает авторизация?» может привести к файлам, где встречаются auth, login, token или session. Но рабочий ответ часто лежит в цепочке: middleware проверяет заголовок, вызывает сервис, сервис читает конфиг, конфиг зависит от env, а refresh-token логика живёт отдельно и ломает всю картину.

Векторный поиск находит похожие места, но плохо показывает путь между ними.

Векторный поиск отдаёт похожие, но разрозненные совпадения; граф Graphify связывает их в реальный путь через auth.

Поэтому вокруг coding agents появляется слой карты. Не «найди похожий текст», а «покажи структуру»: файлы, символы, импорты, вызовы, кластеры, узлы с высокой связностью и неожиданные пересечения.

Graphify — это как раз такой слой. Не замена памяти, а навигация для агента: где что лежит и с чем связано.

Что делает Graphify

Сам проект — safishamsi/graphify. Пакет на PyPI называется graphifyy, но команда остаётся graphify.

Graphify берёт папку и строит knowledge graph. В папке могут быть код, SQL-схемы, Terraform/HCL, shell-скрипты, Markdown, PDF, Office-файлы, Google Workspace shortcut-файлы, изображения, видео, аудио, YouTube-ссылки и MCP-конфиги.

Но внутри важно разделять типы данных.

Код обрабатывается локально через tree-sitter. Для кода Graphify не обязан отправлять файлы в модель: он может детерминированно вытащить структуру — функции, классы, импорты, методы, связи и исходные локации.

Документы, PDF и изображения могут требовать модельный backend для семантического извлечения. Видео и аудио могут транскрибироваться локально через faster-whisper. Поэтому фразу «Graphify локальный» лучше читать аккуратно: кодовый слой локален, но разные типы входных данных обрабатываются по-разному.

Результат складывается в graphify-out/. Основные артефакты:

graph.json — граф для запросов и экспорта;
GRAPH_REPORT.md — отчёт с узлами, связями и вопросами;
HTML-визуализация;
опционально wiki, Obsidian export, GraphML, Neo4j/FalkorDB export и MCP server.

Это уже не «ещё одна документация проекта», а инфраструктурный слой, к которому может обращаться агент.

Как устроен pipeline Graphify

Graphify не сводится к одному запуску «проиндексируй папку». Внутри несколько проходов.

Первый проход — структурное извлечение. Tree-sitter парсит код и вытаскивает AST-сигналы. Так появляются узлы и рёбра, которые можно пометить как EXTRACTED: файл содержит функцию, класс содержит метод, файл импортирует модуль, один символ вызывает другой.

Второй проход — локальная обработка видео и аудио, если они есть. Медиа сначала нужно превратить в текст.

Третий проход — семантическое извлечение из документов, PDF, изображений и других не-кодовых источников. Здесь уже возможны LLM-вызовы. Graphify может запускать параллельных subagents по чанкам файлов, а потом сливать их JSON-фрагменты в общий граф.

После этого идут сборка графа, кластеризация, анализ и генерация выходных файлов.

В архитектурных документах Graphify отдельно описаны модули:

extract.py извлекает узлы и рёбра;
cluster.py кластеризует граф;
analyze.py считает god nodes, surprising connections и suggested questions;
cache.py отвечает за semantic cache;
serve.py поднимает MCP server;
benchmark.py сравнивает чтение raw corpus с чтением subgraph.

Важная деталь: Graphify не прячет степень уверенности. Рёбра могут быть EXTRACTED, INFERRED или AMBIGUOUS. Сомнительные связи уходят в AMBIGUOUS и флагуются на ручную проверку в отчёте.

Это не идеальная гарантия, но это честнее, чем отдавать агенту граф без различия между «нашли в AST» и «модель предположила».

Для кодинга это важно. Агент должен по-разному относиться к связи, которую нашли в коде, и к связи, которую модель предположила по документации.

Пайплайн Graphify: структурный, медиа- и семантический проходы собирают папку в граф; сплошное извлечено, пунктир домыслен.

Почему query в Graphify не должен быть магическим

Одна из самых полезных деталей Graphify — constrained query expansion.

Перед traversal агент должен расширять пользовательский вопрос только через словарь самого графа. Он не должен придумывать термины из своей памяти. Он читает labels из graph.json, строит небольшой словарь, выбирает токены, которые реально есть в графе, и только потом запускает graphify query.

Это хорошая защита от типичной агентной галлюцинации.

Плохой агент получает вопрос «где у нас аутентификация?» и начинает искать authentication service, хотя в проекте всё называется auth, jwt, credentials и session_middleware. Или ещё хуже — отвечает из общего опыта, а не из конкретного проекта.

Хороший Graphify workflow заставляет его сначала принять словарь проекта.

Пример команды:

graphify query "auth token database" --budget 3000

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

Это звучит мелко, но именно из таких правил складывается нормальная агентная дисциплина.

Incremental update важнее, чем кажется

Первый запуск любого индексатора можно пережить. Настоящая проверка начинается на второй неделе.

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

Graphify решает это через manifest, SHA256 cache и incremental update.

Команда:

graphify hook install

ставит post-commit hook. После коммита граф может обновляться автоматически. Если изменились только code files, Graphify может пропустить semantic extraction и запустить только AST-часть. Это дешевле и быстрее.

В update-процессе есть важная инженерная деталь: при обновлении нужно удалять старые узлы для изменённых файлов перед вставкой новых AST-узлов. Иначе dedup может схлопнуть одинаково названные символы из разных файлов.

В changelog такие вещи выглядят скучно, но они показывают зрелость инструмента. Проблемы появляются не в happy path, а когда граф живёт дольше одного запуска.

Другой пример — merge driver, чтобы graph.json не оставался с conflict markers после параллельных коммитов. Это та же мысль: граф кода становится командным артефактом. Значит, у него появляются обычные проблемы командных артефактов: merge, freshness, corrupt manifest, stale nodes, ambiguous collisions.

Если статья про Graphify не говорит об этом, она получается рекламной, а не инженерной.

MCP превращает Graphify из отчёта в рабочий инструмент

Graphify можно использовать как CLI, но более интересная форма — MCP server.

Пример:

python -m graphify.serve graphify-out/graph.json
python -m graphify.serve graphify-out/graph.json --transport http --port 8080

Через MCP агент получает инструменты:

query_graph;
get_node;
get_neighbors;
shortest_path;
list_prs;
get_pr_impact;
triage_prs.

Здесь меняется режим работы. Агент больше не просит человека открыть HTML-отчёт. Он сам обращается к графу во время задачи.

Но MCP поднимает вопросы безопасности. В SECURITY.md Graphify описывает базовую модель: инструмент локальный, MCP по умолчанию stdio, path traversal ограничен graphify-out/, labels санитизируются, HTML escaping есть, source files не исполняются, tree-sitter только парсит AST.

При HTTP transport появляется отдельное правило: не выставлять наружу без --api-key. README прямо говорит: если bind на 0.0.0.0, ставьте API key.

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

Где Graphify не надо натягивать

Graphify не должен становиться свалкой всего подряд.

Если проект маленький — шесть файлов и одна папка — ценность графа будет скорее в визуальной ясности, а не в экономии контекста. Документы Graphify сами говорят: token reduction сильнее чувствуется на больших корпусах. Маленький проект агент и так может прочитать целиком.

Graphify также не заменяет архитектурную документацию. Он может показать связи, но не обязан объяснять продуктовую причину, почему модуль устроен именно так. Для этого нужны CLAUDE.md, ADR, заметки, issue history или память разговоров.

И ещё: граф может устаревать. Любой автоматический слой контекста опасен, если агент начинает верить ему сильнее, чем source files. Правильная дисциплина такая: Graphify указывает, куда смотреть; исходники подтверждают, что там правда.

MemPalace решает другую половину проблемы

MemPalace начинается не с карты кода, а с потери истории.

Claude Code, Codex, OpenCode и похожие инструменты создают много ценного контекста в разговорах: решения, объяснения, найденные баги, предпочтения, отложенные задачи, причины отказа от вариантов. Эта информация часто не попадает в repo docs. Она живёт в локальных JSONL, в сессиях, в чате и в голове пользователя.

MemPalace пытается забрать эту историю в локальную память.

MemPalace строится на verbatim first: сначала хранить исходный текст, а не summary. Это важно, потому что summary почти всегда теряет то, что завтра окажется главным: формулировку запрета, странную деталь ошибки, точное имя файла, тон пользовательского решения.

Модель дворца памяти в MemPalace выглядит так:

wing — проект, человек или область;
room — тема внутри wing;
hall — тип памяти: facts, events, discoveries, preferences, advice;
closet — компактный AAAK-сжатый вид поверх drawers, а не отдельное хранилище;
drawer — исходный фрагмент текста.

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

Как MemPalace устроен как локальный слой

По repo и pyproject видно, что MemPalace строится вокруг CLI, MCP server и сменяемых backends.

Базовая установка:

uv tool install mempalace
mempalace init ~/projects/myapp

Примеры работы:

mempalace mine ~/my-project
mempalace mine ~/.claude/projects/ --mode convos
mempalace search "why GraphQL"
mempalace wake-up

По умолчанию используется ChromaDB. Есть backend-интерфейс, sqlite_exact, Qdrant, Postgres + pgvector. В base.py видны typed result dataclasses, contracts для backend/collection, namespace isolation capability и maintenance hooks вроде analyze/compact.

Это уже не «скрипт поиска по папке», а попытка сделать сменяемый storage layer.

MCP server MemPalace даёт инструменты вроде:

mempalace_status;
mempalace_list_wings;
mempalace_list_rooms;
mempalace_get_taxonomy;
mempalace_search;
mempalace_add_drawer;
mempalace_delete_drawer;
mempalace_reconnect.

В коде MCP server заметны практические проблемы, которые редко попадают в маркетинговые описания.

Например, stdout должен содержать только JSON-RPC, но зависимости вроде ChromaDB/onnxruntime могут писать баннеры и ошибки в stdout. MemPalace редиректит stdout в stderr до тяжёлых импортов, чтобы не ломать JSON parser клиента.

Есть idle auto-exit для старых MCP servers, особенно из-за Windows/HNSW file handles. Есть fallback на SQLite/BM25, если Chroma/HNSW сегмент расходится с sqlite достаточно сильно, чтобы это стало опасно.

Это скучные детали. Но именно они показывают, что память агента как продукт упирается не в красивую метафору, а в file handles, stdout, locking, fallback search и repair paths.

Hooks важнее, чем ручной search

MemPalace становится полезнее, когда встроен в lifecycle агента.

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

Поэтому вокруг MemPalace появляются плагины и hooks:

Claude Code Stop и PreCompact hooks;
OpenCode plugin с wake-up injection, pre-compaction rescue, background mining, idle/crash auto-save;
Hermes plugin с prefetch на user turn, session-end diary, pre-compression drawer, memory mirroring;
Codex/Cursor/Antigravity plugin configs.

Правильный паттерн простой: память должна срабатывать на событиях сессии.

Перед началом работы агент получает wake-up context. Перед compaction система спасает важный контекст. После завершения сессии пишет diary или drawers. В следующей сессии это можно найти.

Если заставлять пользователя вручную копировать итоги в память, всё развалится на третьем дне.

Benchmarks MemPalace надо читать осторожно

MemPalace заявляет сильные retrieval numbers. В README есть headline: 96.6% R@5 raw on LongMemEval, zero API calls. В benchmark docs есть воспроизводимые команды для LongMemEval, LoCoMo, ConvoMem и MemBench.

Но R@5 — это не end-to-end качество ответа. Это значит, что нужный документ или сессия попали в top-5 retrieval results. Метрика полезная, но она не доказывает, что агент потом правильно ответит, сопоставит факты и не перепутает старое решение с новым.

Сам проект это тоже признаёт: сравнивать R@5 с QA accuracy других систем некорректно.

И здесь стоит быть честным до конца. Цифру публично разобрали. 96.6% — это vector-search ChromaDB по verbatim-тексту; «дворцовая» структура wings/rooms в этом бенчмарке не участвует как отдельный алгоритм. Она работает как metadata filtering — стандартный приём для векторной БД.

После обсуждения проект сменил тэглайн с «highest-scoring AI memory system ever benchmarked» на «best-benchmarked open-source». То есть число может быть честным в узком смысле — как опубликованный zero-API retrieval recall на LongMemEval, — но оно не доказывает, что сама идея «дворца» даёт прирост качества.

Поэтому честный вывод такой: MemPalace выглядит сильным как retrieval layer для старых сессий, но production-качество зависит от того, как агент использует найденный фрагмент, как память фильтруется, как удаляются секреты, как решаются конфликты и устаревание.

Главная граница между Graphify и MemPalace

Graphify работает с рабочим пространством. MemPalace работает с историей работы.

Graphify хранит карту кода и отвечает «где», MemPalace хранит историю решений и отвечает «почему»; исходники остаются источником правды.

Graphify строит граф того, что есть в проекте: файлы, функции, документы, схемы, связи, кластеры.

MemPalace хранит то, что происходило вокруг проекта: разговоры, решения, предпочтения, сессии, reasoning breadcrumbs, старые объяснения.

Graphify может ответить:

Какие узлы связаны с auth flow?
Как RateLimiter связан с API middleware?
Какие файлы затрагивает этот PR?
Где в графе находится DatabasePool?
Какие модули неожиданно связаны между собой?

MemPalace может ответить:

Почему мы отказались от прошлого auth-подхода?
Где обсуждали миграцию GraphQL?
Что пользователь просил не делать в этом проекте?
Какая была причина этого костыля?
Что надо вспомнить перед продолжением задачи?

Если Graphify отвечает на второй тип вопросов, он будет притворяться. Если MemPalace отвечает на первый тип вопросов, он будет искать фрагменты разговора вместо карты кода.

Хорошая система не заставляет один слой делать работу другого.

Как соединить их в нормальный workflow

Я бы собирал не «agent memory stack», а context hierarchy.

Слои контекста по порядку: карта проектов, MemPalace wake-up, граф Graphify, исходники, запись результата.

Слой 0: короткая карта проектов. Где какие проекты лежат, какой стек, какие серверы, какие правила. Это может быть AGENTS.md, CLAUDE.md, Obsidian index или простой markdown-файл.

Слой 1: MemPalace wake-up context. Перед началом задачи агент достаёт последние решения, предпочтения, ограничения и старые обсуждения по проекту.

Слой 1.5: Graphify graph. Перед чтением файлов агент спрашивает карту: какие узлы относятся к задаче, какой shortest path, какие соседи у ключевого узла, какие affected areas.

Слой 2: исходники. Только теперь агент открывает конкретные файлы.

Слой 3: запись результата. После задачи обновляется Graphify, а MemPalace сохраняет новые решения и фрагменты, которые должны пережить сессию.

Команды могут выглядеть так:

uv tool install graphifyy
uv tool install mempalace

graphify install --project
graphify extract .
graphify hook install

mempalace init ~/projects/myapp
mempalace mine ~/.claude/projects/ --mode convos
mempalace search "auth migration"

Для команды я бы добавил правило в AGENTS.md или CLAUDE.md:

Before reading source files for architecture questions, query Graphify.
Before proposing changes that may repeat prior decisions, check MemPalace.
After completing a meaningful task, update the graph and save durable decisions.

Это простое правило лучше, чем вера в «агент сам догадается». Не догадается. Агент делает то, что workflow делает дешёвым и очевидным.

Где companion-проекты добавляют смысл

Companion repos вокруг Graphify и MemPalace полезны не как «ещё ссылки», а как признаки проблем, которые появляются у пользователей.

lucasrosati/claude-code-memory-setup соединяет Obsidian и Graphify. Там хорошо видно разделение: Obsidian хранит решения и проектные заметки, Graphify хранит карту кода, chat import pipeline подтягивает разговоры. Это почти тот же layered workflow, только с Obsidian вместо MemPalace.

ai-context-hierarchy говорит ещё проще: агенту нужен top-down путь. Сначала глобальная карта проектов, потом проектный контекст, потом Graphify, потом файлы. Это человеческая навигация, перенесённая в агента.

slurp показывает проблему второго порядка. Даже если Graphify построил большой граф, агенту нельзя каждый раз давать весь граф. Slurp выбирает релевантный subgraph под token budget. Следующий слой после «построить карту» — «выдать маленькую карту под текущий вопрос».

GraphiQuest добавляет человеческий UI: 3D-dashboard, hotspots, orphan candidates, trace. Не всем нужен 3D-граф, но идея полезна: граф кода может быть не только инструментом агента, но и способом человеку увидеть странные связи.

graphify-go и graphify-ts показывают инфраструктурное давление. Когда инструмент нужен каждый день, людям важны скорость, один бинарник, меньше Python dependency hell, WASM/tree-sitter и интеграция с конкретной средой.

Со стороны MemPalace похожую роль играют opencode-plugin-mempalace, hermes-plugin-mempalace, mempalace-evolve и Rust-порт. Они показывают, что боль не в поисковой команде, а в lifecycle: auto-save, pre-compaction, diary, review queue, concurrency, packaging.

Что я бы не делал

Я бы не начинал с гигантского «зальём всё в память». Это почти гарантированно создаст мусор.

Не надо автоматически сохранять каждую мысль модели как durable memory. Модель может ошибаться. Она может временно поверить в гипотезу, которую через пять минут опровергли тесты. Если это попадёт в память без proof/status, будущий агент получит ядовитый контекст.

Не надо отдавать агенту весь Graphify report в каждый prompt. Карта нужна для навигации, а не как новый способ забить контекст.

Не надо считать graph.json истиной. Это индекс, не source of truth. Для изменений в коде source of truth остаётся репозиторий.

Не надо игнорировать секреты. И Graphify, и MemPalace могут пройтись по чувствительным файлам, если им разрешить. Нужны .graphifyignore, понятные exclude rules, осторожность с Claude/Codex logs и ручная проверка того, что попадает в долговременную память.

Не надо принимать benchmark headlines без чтения метрик. Token reduction, retrieval recall, QA accuracy и agent task success измеряют разные вещи.

Более честная рекомендация

Если агент часто блуждает по репозиторию, начните с Graphify.

Проверьте не stars и не HTML-визуализацию, а один сценарий: задайте агенту архитектурный вопрос до Graphify и после Graphify. Сколько файлов он открыл? Сколько tool calls сделал? Быстрее ли нашёл правильный узел? Уменьшилась ли доля случайного чтения?

Если агент забывает решения, начните с MemPalace.

Проверьте не красивую структуру wings/rooms, а поиск по старым фразам. Возьмите реальную прошлую сессию, найдите решение, которое вы помните, и посмотрите, достаёт ли MemPalace правильный drawer. Потом проверьте wake-up context: помогает ли он начать новую сессию без пересказа всей истории?

Если есть обе проблемы, соединяйте слои.

Минимальная зрелая схема:

AGENTS.md / CLAUDE.md: короткая карта проекта и правила
Graphify: структурная карта репозитория
MemPalace: история решений и разговоров
Hooks: обновление после изменений и сохранение перед compaction/session end
Ignore rules: защита от мусора и секретов
Verification: агент цитирует source_location или drawer, а не говорит «я помню»

Это не звучит как магия. И хорошо. Агентная память должна быть скучной инфраструктурой.

Финальный тезис

Graphify и MemPalace не стоит объяснять как два варианта одного инструмента.

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

MemPalace — история. Он сохраняет старые разговоры, решения и проектный опыт, который не всегда попадает в репозиторий.

Хороший агентный workflow начинается не с «дать модели больше контекста». Он начинается с разделения контекста по типам.

Карта отвечает за пространство.

Память отвечает за время.

Исходники отвечают за правду.

Если держать эти слои отдельно, агент меньше блуждает, меньше повторяется и чаще начинает работу с того места, где вы остановились, а не с очередного grep по всему дому.