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»
и «Александр Смирнов» схлопываются в один узел — при условии, что маппинг в карте есть.
Команды
| Команда |
Что делает |
stats |
Узлы/рёбра, разбивка по типам и rel, orphans, dangling. Всегда отсюда бери свежие цифры. |
search <substr> |
Узлы по подстроке имени или заголовка (до 40). Первый шаг: найти точное имя узла. |
neighbors <name> [depth] |
Соседи узла на глубину depth (по умолч. 1). Помечает цели без заметки. |
path <a> <b> |
Кратчайший путь между двумя узлами (BFS, ненаправленный). |
timeline <name> |
Цепочка supersedes: что узел заместил и кем замещён (bi-temporal история). |
cases <substr> |
Кейсы (сессии) по проекту/подстроке — каталог «мои сессии по X» (нужен Layer 2). |
hubs [N] |
Топ-N самых связанных узлов (центры тяжести памяти). |
orphans |
Узлы без единого ребра — не вплетены в граф. |
dangling |
[[ссылки]] на несуществующие узлы — кандидаты завести заметку. |
gaps [stale_days] |
Gap-анализ (0 LLM): orphans + dangling + stale-hubs + superseded-unmarked. Порог устаревания по умолч. 45 дней. |
build |
Пересобрать граф из заметок (+ кейсбука, если есть). Прогоняется в dream; вручную — после крупной правки памяти. |
Имена узлов часто содержат пробелы, кириллицу и префиксы (proj:, person:) — оборачивай в кавычки:
python ~/.claude/scripts/memory_graph.py neighbors "person:Мария Иванова" 2
Процедура (типовой запрос)
- Найди узел. Точного имени обычно не знаешь →
search <подстрока>. Возьми name из вывода.
- Выбери обход под вопрос:
- «что связано / кто рядом» →
neighbors <name> [depth] (depth 2 для второго кольца).
- «как связаны A и B» →
path <A> <B>.
- «что заместило / хронология» →
timeline <name>.
- «мои сессии по проекту» →
cases <project>.
- «центры / что забыто» →
hubs, orphans, dangling, gaps.
- Синтезируй — прочитай реальные заметки и кейсы по путям, не пересказывай сам граф.
Файл заметки лежит в колонке
file таблицы nodes; кейс — по jsonl_path.
- Применяй невидимо — как собственный опыт, без «судя по графу памяти»
(если не спросили источник).
Выход
Скрипт печатает 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
Чек-лист
Файлы
~/.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.
1---2name: graph-memory3description: "Локальный граф твоей памяти (SQLite, офлайн): соседи, пути, хронология, хабы, разрывы. Триггеры: «что связано с», «хронология проекта», «мои сессии по проекту», «висячие ссылки в памяти». НЕ: уборка→dream; запись→memory-agent; поиск фразы→search_chats.py."4user_invocable: true5trigger: "graph"6arguments: "[command] [args]"7metadata:8 source: https://skillmd.com/skills/jhamidun/graph-memory9---1011# Graph Memory — локальный граф знаний (offline)1213Запрашиваемый граф поверх твоей памяти. Ноль сети, ноль туннелей — один Python-скрипт14и один SQLite-файл. Отвечает на многохоповые вопросы («кто/что/как связано с X»,15«хронология», «мои кейсы по проекту»), которые линейный поиск по заметкам не тянет.1617**Два пути, один движок:**1819- **MCP-инструменты** `graph_build`, `graph_stats`, `graph_neighbors`, `graph_path`,20 `graph_timeline`, `graph_hubs`, `graph_orphans`, `graph_search`, `graph_cases`,21 `graph_dangling`, `graph_gaps` — сервер `graph-memory` включён в `settings.json` по умолчанию.22- **CLI** — то же самое из терминала:23 `python ~/.claude/scripts/memory_graph.py {build|stats|neighbors|path|timeline|hubs|orphans|search|dangling|cases|gaps} [args]`2425**Хранилище:** `~/.claude/memory-graph/graph.db` (SQLite). Размер бери из `stats`, не хардкодь.26**Актуальность:** снимок на момент последнего `build` (обычно прогоняется в `dream`).2728## Первый запуск — база едет пустой2930Граф собирается из **твоих** заметок; вместе с паком не приезжает ничего, кроме движка.31Пока ты не написал ни одной заметки, любая команда честно вернёт ноль — это не поломка.3233```bash34# 1. Заметки живут здесь. Каталог создаётся при первой записи через memory-agent.35ls ~/.claude/projects/*/memory/*.md # пусто — значит писать ещё нечего3637# 2. Собрать граф (создаст ~/.claude/memory-graph/graph.db)38python ~/.claude/scripts/memory_graph.py build3940# 3. Убедиться, что он видит заметки41python ~/.claude/scripts/memory_graph.py stats42```4344`nodes=0` после `build` при непустой папке заметок — смотри, есть ли у файлов frontmatter45`name`/`type` и `[[wikilinks]]`: узлы и рёбра берутся оттуда.4647## Когда использовать4849- Вопрос о ПРОШЛОМ: решения, грабли, статусы проектов, «что мы делали с X», «с кем работал над Y».50- Нужна связь через несколько шагов: «как связаны A и B», путь между сущностями.51- Хронология замен/решений: «что заместило старую заметку», «timeline проекта».52- Обзорные: топ-хабы памяти, орфаны (несвязанные заметки), висячие ссылки (кандидаты на новую заметку).53- Каталог кейсов: «покажи мои сессии по проекту X» (если у тебя собран Layer 2, см. ниже).5455Для полнотекстового поиска по сырым чатам — `~/.claude/tools/search_chats.py` (другой56инструмент). Граф отвечает на структурные и связевые вопросы, не на «найди фразу».5758> **Граница с `memory-agent`, `save-knowledge-base`, `dream` — все четыре про одну память.**59> Этот навык **только читает**: он не пишет ни одной заметки и не меняет ни одного файла60> (кроме `build`, который пересобирает снимок). Поэтому любая просьба «запомни» сюда не61> попадает: готовый документ с названными триггерами → `save-knowledge-base`, наблюдение62> без явного места → `memory-agent` (он выберет слой). Прибраться в уже записанном → `dream`;63> он же обычно и прогоняет `build`, так что свежесть графа — его работа, не твоя. Правило:64> **вопрос про СВЯЗИ и хронологию → сюда; «найди фразу» → `search_chats.py`; любое65> «запомни» → `save-knowledge-base`/`memory-agent`.**6667## Что внутри графа (модель данных)6869Две склеенные схемы в одной БД.7071**Layer 1 — курированные заметки** (`~/.claude/projects/<project>/memory/*.md`) — работает72сразу, ничего настраивать не нужно:7374- Узел = заметка. `id` = frontmatter `name` или имя файла. Тип из frontmatter `type`:75 `user` / `feedback` / `project` / `reference` / `memory`.76- Рёбра: `[[wikilinks]]` → `rel=link`; frontmatter `supersedes`/`superseded_by` →77 `rel=supersedes` (bi-temporal: факт не удаляем, а замещаем).7879**Layer 2 — кейсбук из истории чатов** (`~/_casebook/`) — **опционально**. Пака он не80касается: движок ищет каталог, не находит и молча собирает граф из одного Layer 1.81Если ты выгружаешь свои сессии в такой формат сам, схема ожидается такая:8283- Узлы-сущности с префиксами: `case:<session_id>` (сессия-кейс), `proj:<name>`,84 `person:<Имя>`, `company:<X>`, `tool:<Y>`.85- Рёбра: `involves` (case→person), `for_company` (case→company), `uses` (case→tool),86 `in_project` / `in_cluster` (case→proj).87- Файлы: `all_cards_v2.json` и/или `cards_db/*.json`, сущности `entities_v1/*.json`,88 кластеры `clusters.json`, канон-карты имён `canon/*_map.json`.89- L1↔L2 мост: `about` — заметка → `proj:` по дистинктивному ключу в имени-слаге.9091Имена сущностей нормализуются канон-картами (вариант→канон), поэтому «Alexander Smith»92и «Александр Смирнов» схлопываются в один узел — **при условии**, что маппинг в карте есть.9394## Команды9596| Команда | Что делает |97|---------|-----------|98| `stats` | Узлы/рёбра, разбивка по типам и rel, orphans, dangling. **Всегда отсюда бери свежие цифры.** |99| `search <substr>` | Узлы по подстроке имени или заголовка (до 40). Первый шаг: найти точное имя узла. |100| `neighbors <name> [depth]` | Соседи узла на глубину depth (по умолч. 1). Помечает цели без заметки. |101| `path <a> <b>` | Кратчайший путь между двумя узлами (BFS, ненаправленный). |102| `timeline <name>` | Цепочка `supersedes`: что узел заместил и кем замещён (bi-temporal история). |103| `cases <substr>` | Кейсы (сессии) по проекту/подстроке — каталог «мои сессии по X» (нужен Layer 2). |104| `hubs [N]` | Топ-N самых связанных узлов (центры тяжести памяти). |105| `orphans` | Узлы без единого ребра — не вплетены в граф. |106| `dangling` | `[[ссылки]]` на несуществующие узлы — кандидаты завести заметку. |107| `gaps [stale_days]` | Gap-анализ (0 LLM): orphans + dangling + stale-hubs + superseded-unmarked. Порог устаревания по умолч. 45 дней. |108| `build` | Пересобрать граф из заметок (+ кейсбука, если есть). Прогоняется в `dream`; вручную — после крупной правки памяти. |109110Имена узлов часто содержат пробелы, кириллицу и префиксы (`proj:`, `person:`) — оборачивай в кавычки:111`python ~/.claude/scripts/memory_graph.py neighbors "person:Мария Иванова" 2`112113## Процедура (типовой запрос)1141151. **Найди узел.** Точного имени обычно не знаешь → `search <подстрока>`. Возьми `name` из вывода.1162. **Выбери обход** под вопрос:117 - «что связано / кто рядом» → `neighbors <name> [depth]` (depth 2 для второго кольца).118 - «как связаны A и B» → `path <A> <B>`.119 - «что заместило / хронология» → `timeline <name>`.120 - «мои сессии по проекту» → `cases <project>`.121 - «центры / что забыто» → `hubs`, `orphans`, `dangling`, `gaps`.1223. **Синтезируй** — прочитай реальные заметки и кейсы по путям, не пересказывай сам граф.123 Файл заметки лежит в колонке `file` таблицы nodes; кейс — по `jsonl_path`.1244. **Применяй невидимо** — как собственный опыт, без «судя по графу памяти»125 (если не спросили источник).126127## Выход128129Скрипт печатает plain-text в stdout (UTF-8, форсится под Windows-консоль). Примеры формата:130131- `neighbors`: `d1 <src> --<rel>--> <dst>` (плюс `(нет заметки)` для висячих целей).132- `path`: `A -> X -> B` или `нет пути A .. B`.133- `stats`: `nodes=… edges=…`, затем словари `by type` / `by rel`.134135## Пример136137Подставь свои имена — граф знает только то, что ты в него записал.138139```bash140# 1. найти узел141python ~/.claude/scripts/memory_graph.py search MyProject142# proj:MyProject -- MyProject143# case:... -- 2026-06-… [MyProject] …144145# 2. второе кольцо связей проекта146python ~/.claude/scripts/memory_graph.py neighbors "proj:MyProject" 2147148# 3. как связаны компания и проект149python ~/.claude/scripts/memory_graph.py path "company:SomeCorp" "proj:MyProject"150151# 4. все мои сессии по проекту152python ~/.claude/scripts/memory_graph.py cases MyProject153154# 5. что память НЕ знает / где дыры155python ~/.claude/scripts/memory_graph.py gaps 30156```157158## Чек-лист159160- [ ] Сначала `search` → взял точное `name`, а не угадал.161- [ ] Имена с пробелами/префиксом/кириллицей — в кавычках.162- [ ] Цифры (узлы/типы) — из `stats`, не по памяти и не из этого файла.163- [ ] Прочитал реальные заметки и кейсы по найденным путям перед ответом.164- [ ] Чувствительное (семья, финансы, здоровье, конфликты) первым не поднимал, пока165 владелец памяти сам не затронул тему.166- [ ] После крупной правки памяти или если граф выглядит устаревшим — `build`167 (обычно это делает `dream`).168169## Файлы170171- `~/.claude/scripts/memory_graph.py` — единственный движок (build + все запросы).172- `~/.claude/mcps/graph-memory/server.py` — тонкая MCP-обёртка над тем же движком.173- `~/.claude/memory-graph/graph.db` — SQLite-снимок (nodes, edges). Создаётся первым `build`.174- `~/.claude/projects/<project>/memory/*.md` — источник Layer 1 (заметки).175- `~/_casebook/` — источник Layer 2, опционально (см. выше).176- `references/gbrain-typed-edges-gap-analysis.md` — откуда взялся `gaps` и что решили не тянуть.177178## Известные ограничения (honest)179180- **Снимок, не live.** Граф отражает состояние на момент последнего `build`. Свежие заметки181 появятся в нём только после пересборки.182- **База приезжает пустой.** Первые дни граф будет отвечать «ничего не найдено» — это183 нормально, ему нечего показывать, пока нет заметок.184- **Нормализация имён неполна.** Схлопывание вариантов работает лишь для того, что есть185 в канон-картах; незамапленные варианты остаются отдельными узлами.186- **`path` ненаправленный.** BFS игнорирует направление и тип ребра — путь может проходить187 через слабую связь `about`/`link`.188- **Layer 2 никто за тебя не соберёт.** Без `~/_casebook/` команда `cases` вернёт пусто,189 остальные работают.190- **Инкрементальных апдейтов нет** — только полная пересборка `build`.