Graph Memory

Graph Memory — локальный граф знаний (offline)

Запрашиваемый граф поверх твоей памяти. Ноль сети, ноль туннелей — один Python-скрипт и один SQLite-файл. Отвечает на многохоповые вопросы («кто/что/как связано с X», «хронология», «мои кейсы по проекту»), которые линейный поиск по заметкам не тянет.

Два пути, один движок:

• MCP-инструменты graph_build, graph_stats, graph_neighbors, graph_path, graph_timeline, graph_hubs, graph_orphans, graph_search, graph_cases, graph_dangling, graph_gaps — сервер graph-memory включён в settings.json по умолчанию.
• CLI — то же самое из терминала: python ~/.claude/scripts/memory_graph.py {build|stats|neighbors|path|timeline|hubs|orphans|search|dangling|cases|gaps} [args]

Хранилище: ~/.claude/memory-graph/graph.db (SQLite). Размер бери из stats, не хардкодь. Актуальность: снимок на момент последнего build (обычно прогоняется в dream).

Первый запуск — база едет пустой

Граф собирается из твоих заметок; вместе с паком не приезжает ничего, кроме движка. Пока ты не написал ни одной заметки, любая команда честно вернёт ноль — это не поломка.

# 1. Заметки живут здесь. Каталог создаётся при первой записи через memory-agent.
ls ~/.claude/projects/*/memory/*.md          # пусто — значит писать ещё нечего

# 2. Собрать граф (создаст ~/.claude/memory-graph/graph.db)
python ~/.claude/scripts/memory_graph.py build

# 3. Убедиться, что он видит заметки
python ~/.claude/scripts/memory_graph.py stats

nodes=0 после build при непустой папке заметок — смотри, есть ли у файлов frontmatter name/type и [[wikilinks]]: узлы и рёбра берутся оттуда.

Когда использовать

• Вопрос о ПРОШЛОМ: решения, грабли, статусы проектов, «что мы делали с X», «с кем работал над Y».
• Нужна связь через несколько шагов: «как связаны A и B», путь между сущностями.
• Хронология замен/решений: «что заместило старую заметку», «timeline проекта».
• Обзорные: топ-хабы памяти, орфаны (несвязанные заметки), висячие ссылки (кандидаты на новую заметку).
• Каталог кейсов: «покажи мои сессии по проекту X» (если у тебя собран Layer 2, см. ниже).

Для полнотекстового поиска по сырым чатам — ~/.claude/tools/search_chats.py (другой инструмент). Граф отвечает на структурные и связевые вопросы, не на «найди фразу».

Граница с memory-agent, save-knowledge-base, dream — все четыре про одну память. Этот навык только читает: он не пишет ни одной заметки и не меняет ни одного файла (кроме build, который пересобирает снимок). Поэтому любая просьба «запомни» сюда не попадает: готовый документ с названными триггерами → save-knowledge-base, наблюдение без явного места → memory-agent (он выберет слой). Прибраться в уже записанном → dream; он же обычно и прогоняет build, так что свежесть графа — его работа, не твоя. Правило: вопрос про СВЯЗИ и хронологию → сюда; «найди фразу» → search_chats.py; любое «запомни» → save-knowledge-base/memory-agent.

Что внутри графа (модель данных)

Две склеенные схемы в одной БД.

Layer 1 — курированные заметки (~/.claude/projects/<project>/memory/*.md) — работает сразу, ничего настраивать не нужно:

• Узел = заметка. id = frontmatter name или имя файла. Тип из frontmatter type: user / feedback / project / reference / memory.
• Рёбра: [[wikilinks]] → rel=link; frontmatter supersedes/superseded_by → rel=supersedes (bi-temporal: факт не удаляем, а замещаем).

Layer 2 — кейсбук из истории чатов (~/_casebook/) — опционально. Пака он не касается: движок ищет каталог, не находит и молча собирает граф из одного Layer 1. Если ты выгружаешь свои сессии в такой формат сам, схема ожидается такая:

• Узлы-сущности с префиксами: case:<session_id> (сессия-кейс), proj:<name>, person:<Имя>, company:<X>, tool:<Y>.
• Рёбра: involves (case→person), for_company (case→company), uses (case→tool), in_project / in_cluster (case→proj).
• Файлы: all_cards_v2.json и/или cards_db/*.json, сущности entities_v1/*.json, кластеры clusters.json, канон-карты имён canon/*_map.json.
• L1↔L2 мост: about — заметка → proj: по дистинктивному ключу в имени-слаге.

Имена сущностей нормализуются канон-картами (вариант→канон), поэтому «Alexander Smith» и «Александр Смирнов» схлопываются в один узел — при условии, что маппинг в карте есть.

Команды

Имена узлов часто содержат пробелы, кириллицу и префиксы (proj:, person:) — оборачивай в кавычки: python ~/.claude/scripts/memory_graph.py neighbors "person:Мария Иванова" 2

Процедура (типовой запрос)

1. Найди узел. Точного имени обычно не знаешь → search <подстрока>. Возьми name из вывода.
2. Выбери обход под вопрос:
   • «что связано / кто рядом» → neighbors <name> [depth] (depth 2 для второго кольца).
   • «как связаны A и B» → path <A> <B>.
   • «что заместило / хронология» → timeline <name>.
   • «мои сессии по проекту» → cases <project>.
   • «центры / что забыто» → hubs, orphans, dangling, gaps.
3. Синтезируй — прочитай реальные заметки и кейсы по путям, не пересказывай сам граф. Файл заметки лежит в колонке file таблицы nodes; кейс — по jsonl_path.
4. Применяй невидимо — как собственный опыт, без «судя по графу памяти» (если не спросили источник).

Выход

Скрипт печатает plain-text в stdout (UTF-8, форсится под Windows-консоль). Примеры формата:

• neighbors: d1 <src> --<rel>--> <dst> (плюс (нет заметки) для висячих целей).
• path: A -> X -> B или нет пути A .. B.
• stats: nodes=… edges=…, затем словари by type / by rel.

Пример

Подставь свои имена — граф знает только то, что ты в него записал.

# 1. найти узел
python ~/.claude/scripts/memory_graph.py search MyProject
#   proj:MyProject  -- MyProject
#   case:...        -- 2026-06-… [MyProject] …

# 2. второе кольцо связей проекта
python ~/.claude/scripts/memory_graph.py neighbors "proj:MyProject" 2

# 3. как связаны компания и проект
python ~/.claude/scripts/memory_graph.py path "company:SomeCorp" "proj:MyProject"

# 4. все мои сессии по проекту
python ~/.claude/scripts/memory_graph.py cases MyProject

# 5. что память НЕ знает / где дыры
python ~/.claude/scripts/memory_graph.py gaps 30

Чек-лист

• Сначала search → взял точное name, а не угадал.
• Имена с пробелами/префиксом/кириллицей — в кавычках.
• Цифры (узлы/типы) — из stats, не по памяти и не из этого файла.
• Прочитал реальные заметки и кейсы по найденным путям перед ответом.
• Чувствительное (семья, финансы, здоровье, конфликты) первым не поднимал, пока владелец памяти сам не затронул тему.
• После крупной правки памяти или если граф выглядит устаревшим — build (обычно это делает dream).

Файлы

• ~/.claude/scripts/memory_graph.py — единственный движок (build + все запросы).
• ~/.claude/mcps/graph-memory/server.py — тонкая MCP-обёртка над тем же движком.
• ~/.claude/memory-graph/graph.db — SQLite-снимок (nodes, edges). Создаётся первым build.
• ~/.claude/projects/<project>/memory/*.md — источник Layer 1 (заметки).
• ~/_casebook/ — источник Layer 2, опционально (см. выше).
• references/gbrain-typed-edges-gap-analysis.md — откуда взялся gaps и что решили не тянуть.

Известные ограничения (honest)

• Снимок, не live. Граф отражает состояние на момент последнего build. Свежие заметки появятся в нём только после пересборки.
• База приезжает пустой. Первые дни граф будет отвечать «ничего не найдено» — это нормально, ему нечего показывать, пока нет заметок.
• Нормализация имён неполна. Схлопывание вариантов работает лишь для того, что есть в канон-картах; незамапленные варианты остаются отдельными узлами.
• path ненаправленный. BFS игнорирует направление и тип ребра — путь может проходить через слабую связь about/link.
• Layer 2 никто за тебя не соберёт. Без ~/_casebook/ команда cases вернёт пусто, остальные работают.
• Инкрементальных апдейтов нет — только полная пересборка build.