🛠️ Maintenance, updates, and troubleshooting

Your project doesn't stand still: the documentation changes, the code grows, files come and go. The graph needs to keep up — but rebuilding everything from scratch with every commit would be slow and expensive. The answer is the incremental: graphify update . reprocesses only what changed and reuse the rest of the cache.

The maintenance cycle has two steps. First, update the graph (graphify-out/graph.json is the source of truth). Then, if you use the Obsidian vault, export again with --obsidian to regenerate the notes. Remember: the export is derived of the graph — updating the graph doesn’t update the vault by itself.

# headless (terminal puro): só reprocessa o que mudou
graphify update .

# usando a skill dentro do Claude Code, e já re-exportando o vault:
# /graphify . --update --obsidian --obsidian-dir ~/vault/graphify/meu-projeto

↑ The cycle closes: every time the source changes, you run update and re-exports. The graph is the source of truth; the vault is derived from it—which is why you need both steps.

Here’s the pitfall that hurts the most: the Obsidian export is regenerated from scratch with each run. If you opened a generated note, wrote your own reflection in it, and then ran the export again, that edit is overwritten. Graphify doesn’t merge your changes—it recreates the file.

You installed with uv tool install graphifyy, but the terminal responds command not found. No worries: the package was installed; it just isn’t in the PATH of your shell. The uv has a command that fixes this in one step.

# adiciona o diretório de tools do uv ao PATH do shell
uv tool update-shell

# feche e reabra o terminal (ou recarregue o perfil), depois confirme:
graphify --help

This isn’t the only common pitfall during installation and everyday use. The table below is your “symptom → cause → fix” map:

An API key error almost always means one thing: you’re running Graphify headless (in the plain terminal) to extract documents, and semantic extraction requires a model. Inside Claude Code, via /graphify, the session already provides the model—you no doesn’t need any key.

↑ The key only enters the path for right (headless + documents). Extracting code uses tree-sitter (AST) and doesn't need a key even on this path.

# defina a chave na sessão (troque pelo seu valor real)
export ANTHROPIC_API_KEY=<sua-chave>

# agora a extração semântica de documentos funciona headless
graphify extract ./docs

Sometimes the graph comes out noisy (too many entities, many irrelevant) or shallow (few relationships, nothing connects). Most of the time, Graphify isn't to blame—it's the corpus: the graph's quality mirrors the source's quality. "Garbage in, garbage out." The fix starts at the source, not with the command.

# dentro do Claude Code — extração minuciosa (--mode deep é da skill)
/graphify ./docs --mode deep

# alternativa: re-escopar para a parte que importa (headless)
# graphify extract ./src

Always read the GRAPH_REPORT.md: it lists god nodes, connections between communities, and suggested questions — it's your gauge for "did the graph turn out well?".

You built a second brain — now don't miss it. Two fronts: version the Graphify artifacts in git (so the graph is reproducible and you can go back in time), and export your reading progress here in the course (the .json of “My journey”). A backup is what separates “I had it” from “I have it.”

# versione os artefatos do Graphify (o cache pode ficar fora)
echo "graphify-out/cache/" >> .gitignore
git add graphify-out/ .gitignore
git commit -m "chore: snapshot do segundo cérebro (graphify-out)"