Claude Code + Obsidian + Graphify: O Guia Definitivo para Economia de Tokens e Memória Persistente

71.5x menos tokens por sessão com Graphify + memória permanente entre sessões com Obsidian Zettelkasten.

Setup completo para transformar o Claude Code em um agente com memória de longo prazo e consciência total do seu codebase — sem desperdiçar tokens relendo arquivos.

Índice

O Problema
A Solução (Visão Geral)
Parte 1 — Obsidian como Memória Persistente
Parte 2 — Pipeline de Importação de Chats
Parte 3 — Graphify (Knowledge Graph do Codebase)
Parte 4 — Fluxo de Trabalho Completo
Resultados Reais
Troubleshooting

O Problema

Quando você trabalha com o Claude Code, dois problemas consomem seus tokens silenciosamente:

Problema 1 — Amnésia entre sessões. Toda vez que você abre uma sessão nova, precisa re-explicar o projeto: stack, decisões tomadas, bugs em andamento, o que falta fazer. O Claude Code não lembra de nada da sessão anterior.

Problema 2 — Releitura do codebase. O Claude Code relê todos os seus arquivos de código a cada sessão para entender a estrutura. Um projeto com ~40 arquivos consome ~20.000 tokens só para o Claude se orientar — antes de você fazer a primeira pergunta. Se você faz 10 sessões por dia, são 200.000 tokens desperdiçados.

A Solução (Visão Geral)

Dois sistemas complementares, cada um resolvendo um problema:

Camada	Ferramenta	O que resolve	Custo
Memória do projeto	Obsidian Zettelkasten	Amnésia entre sessões	Gratuito
Mapa do código	Graphify	Releitura do codebase	Gratuito (modo AST)
Histórico de conversas	Pipeline de importação	Chats perdidos	Gratuito
Continuidade	Comandos `/retomar` e `/salvar`	Retomar de onde parou	Gratuito

O Obsidian cuida de o que foi decidido (memória declarativa). O Graphify cuida de como o código está organizado (mapa estrutural). Juntos, o Claude Code começa cada sessão sabendo tudo — sem reler nada.

Parte 1 — Obsidian como Memória Persistente

Conceito

Um vault Obsidian único e centralizado funciona como o "segundo cérebro" do Claude Code. Ele armazena decisões, contexto, progresso e conhecimento de todos os seus projetos. As notas seguem o método Zettelkasten: atômicas, densamente interligadas, com metadados padronizados.

O Claude Code acessa esse vault através do CLAUDE.md e de skills customizados.

Estrutura Recomendada

~/vault/                              # vault ÚNICO para todos os projetos
├── CLAUDE.md                         # instruções globais para o Claude Code
├── permanent/                        # notas atômicas consolidadas
├── inbox/                            # captura bruta (ideias, rascunhos)
├── fleeting/                         # rascunhos temporários
├── templates/                        # templates para novas notas
├── logs/                             # session logs globais
├── references/                       # material de referência
├── meu-projeto/                      # MOCs e notas do projeto X
│   ├── projeto/                      #   arquitetura, decisões, convenções
│   ├── pipeline/                     #   fluxos de dados, APIs
│   ├── dados/                        #   schema, modelo de dados
│   ├── features/                     #   features planejadas/implementadas
│   └── logs/                         #   session logs do projeto
├── outro-projeto/                    # MOCs e notas do projeto Y
│   └── ...
├── chats/                            # chats importados do Claude
│   ├── code/                         #   do Claude Code
│   └── web/                          #   do Claude Web/App
└── graphify/                         # knowledge graphs dos codebases
    ├── meu-projeto/                  #   notas do grafo do projeto X
    └── outro-projeto/                #   notas do grafo do projeto Y

Por que um vault único? Ter um vault por projeto fragmenta o conhecimento. Com vault único, uma nota sobre "Supabase Auth" é linkada tanto pelo projeto A quanto pelo B. O graph view mostra conexões entre projetos que você não esperava.

Setup Passo a Passo

Pré-requisitos:

Claude Code instalado e autenticado
Obsidian instalado (gratuito: obsidian.md)

1. Criar o vault:

Obsidian → "Create new vault" → escolha nome e local.

2. Criar a estrutura:

cd ~/vault  # ajuste para seu path
mkdir -p permanent inbox fleeting templates logs references
mkdir -p meu-projeto/{projeto,pipeline,dados,features,logs}

3. Criar o CLAUDE.md:

Este é o arquivo que o Claude Code lê automaticamente. Crie CLAUDE.md na raiz do vault:

# Vault — Instruções para o Claude Code

## O que é este vault
Base de conhecimento centralizada para todos os projetos.
Memória persistente entre sessões.

## Stack dos projetos
- Projeto X: React + Supabase
- Projeto Y: Python + FastAPI
(adapte para seus projetos)

## Regras Zettelkasten

### Criação de notas
- Use wikilinks: [[nome-da-nota]] (não links markdown)
- Frontmatter YAML obrigatório em toda nota
- Nomes de arquivo em kebab-case: `auth-flow.md`, não `Auth Flow.md`
- 1 conceito por nota permanente (atomicidade)
- Mínimo 2 wikilinks por nota (linking denso)

### Frontmatter padrão
---
title: Nome da Nota
tags: [projeto, tema]
created: YYYY-MM-DD
updated: YYYY-MM-DD
status: active
type: permanent
---

### Nunca faça
- Não delete notas sem perguntar
- Não use links markdown para notas internas (use wikilinks)
- Não crie notas sem frontmatter
- Não mude a estrutura de pastas sem documentar

## Comandos de Sessão

### /retomar
Ao receber este comando:
1. Leia os 3 últimos session logs em logs/
2. Leia projeto/decisoes.md do projeto atual
3. Resuma o estado atual e o que falta fazer

### /salvar
Ao receber este comando:
1. Crie session log em logs/YYYY-MM-DD-descricao.md
2. Registre: o que foi feito, decisões tomadas, pendências
3. Adicione wikilinks para notas criadas/alteradas
4. Faça git commit + push se em repositório

4. Criar template de nota:

cat > templates/nota-padrao.md << 'EOF'
---
title: {{title}}
tags: []
created: {{date}}
updated: {{date}}
status: draft
type: permanent
---

# {{title}}

## Contexto

## Detalhes

## Links relacionados
EOF

5. Plugins recomendados no Obsidian:

Plugin	Para que serve	Como instalar
BRAT	Instalar plugins beta	Community Plugins → Browse
3D Graph	Visualização 3D do vault	Via BRAT (v2.4.1)
Folders to Graph	Pastas como nós no graph	Community Plugins → Browse
Calendar	Navegação por daily notes	Community Plugins → Browse

Parte 2 — Pipeline de Importação de Chats

Conceito

Seus chats com o Claude (tanto no Code quanto no Web) contêm decisões, insights e contexto valioso que se perdem no histórico. Este pipeline exporta, processa e importa essas conversas como notas no vault — com frontmatter, tags automáticas e wikilinks para notas existentes.

Componentes

~/scripts/
├── claude_to_obsidian.py          # processador (frontmatter, tags, wikilinks)
└── sync_claude_obsidian.sh        # automação (export + process)

~/claude-exports/                   # staging area temporária (fora do vault)
├── code/                           # exports do Claude Code
└── web/                            # exports do Claude Web

Setup

1. Instalar o extractor do Claude Code:

pip install claude-conversation-extractor

2. Criar diretórios de staging:

mkdir -p ~/claude-exports/code ~/claude-exports/web

3. Criar o script de pós-processamento (~/scripts/claude_to_obsidian.py):

O script deve:

Ler cada .md exportado
Detectar origem (Code vs Web)
Gerar tags automáticas baseadas em keywords do conteúdo
Adicionar frontmatter YAML padronizado
Inserir [[wikilinks]] para notas que já existem no vault
Copiar para chats/code/ ou chats/web/ dentro do vault

Exemplo de mapeamento de keywords para tags:

KEYWORD_TAG_MAP = {
    "python": "python",
    "react": "react",
    "supabase": "supabase",
    "deploy": "deploy",
    "bug": "debugging",
    "refactor": "refactoring",
    # adicione os seus
}

4. Criar o script de automação (~/scripts/sync_claude_obsidian.sh):

#!/bin/bash
EXPORT_DIR="$HOME/claude-exports"
VAULT_DIR="$HOME/vault"  # ajuste para seu path
SCRIPT_DIR="$HOME/scripts"
LOG="$SCRIPT_DIR/sync.log"

echo "[$(date)] Sync iniciado" >> "$LOG"

# Exporta chats do Claude Code
claude-extract --all --output "$EXPORT_DIR/code" 2>> "$LOG"

# Processa e envia pro vault
python3 "$SCRIPT_DIR/claude_to_obsidian.py" \
    --export-dir "$EXPORT_DIR" \
    --vault-dir "$VAULT_DIR" \
    --move 2>> "$LOG"

echo "[$(date)] Sync concluído" >> "$LOG"

5. Agendar execução automática:

chmod +x ~/scripts/sync_claude_obsidian.sh

# Roda todo dia às 22h
(crontab -l 2>/dev/null; echo "0 22 * * * $HOME/scripts/sync_claude_obsidian.sh") | crontab -

6. Para chats do Claude Web:

Instale a extensão "Export Claude Chat to Markdown" no Chrome/Edge. Faça bulk export periódico, salve os .md em ~/claude-exports/web/ e o cron cuida do resto.

7. Adicionar seção ao CLAUDE.md do vault:

## Pipeline de Importação de Chats

### Estrutura
- `chats/code/` → conversas importadas do Claude Code
- `chats/web/` → conversas importadas do Claude Web/App
- Todos os chats recebem frontmatter com `type: chat` e tag `chat-import`

### Filtrar no Graph View
- `tag:chat-import` → só chats
- `-path:chats` → esconder chats

Parte 3 — Graphify (Knowledge Graph do Codebase)

Conceito

Graphify transforma seu codebase em um knowledge graph consultável. Em vez do Claude Code reler cada arquivo, ele consulta o grafo — que é persistente entre sessões e pesa uma fração dos tokens.

Código: processado 100% localmente via tree-sitter AST. Nenhum conteúdo sai da sua máquina.
Cache: SHA256 — re-runs só processam arquivos modificados.
Custo: 0 tokens no modo padrão (AST puro). Modo --deep usa LLM para edges semânticas.
Linguagens: Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, Ruby, C#, Kotlin, Scala, PHP, Swift, Lua, Zig e mais (20 linguagens via tree-sitter).

Setup

1. Instalar:

pip install graphifyy
graphify install

O graphify install cria o skill em ~/.claude/skills/graphify/SKILL.md.

2. Gerar o grafo:

Na raiz do seu projeto:

# Pipeline completa + notas Obsidian no vault centralizado
graphify . --obsidian --obsidian-dir ~/vault/graphify/nome-do-projeto

Output gerado:

seu-projeto/
└── graphify-out/
    ├── graph.json          # grafo consultável (o Claude Code usa este)
    ├── graph.html          # visualização interativa (abra no browser)
    ├── GRAPH_REPORT.md     # god nodes, conexões, métricas
    ├── wiki/               # artigos estilo Wikipedia (navegação do agente)
    └── cache/              # cache SHA256

~/vault/graphify/nome-do-projeto/
    └── (notas Obsidian)    # cada função/módulo como um nó no graph view

3. Atualizar .gitignore:

# Graphify
graphify-out/cache/

Mantenha graph.json e GRAPH_REPORT.md versionados.

4. Adicionar ao CLAUDE.md do projeto:

Adicione ao final do CLAUDE.md na raiz do repositório:

## Context Navigation (Graphify)

### Regra de consulta em 3 camadas
1. **Primeiro:** consulte `graphify-out/graph.json` ou `graphify-out/wiki/index.md`
   para entender a estrutura e conexões do código
2. **Segundo:** consulte o vault Obsidian para contexto de decisões e progresso
3. **Terceiro:** só leia arquivos de código brutos quando for editar
   ou quando as camadas anteriores não tiverem a resposta

### Quando reconstruir o grafo
- Após mudanças estruturais (novos módulos, refactors)
- Comando: `graphify . --update` (só processa arquivos modificados)
- O grafo é persistente — NÃO precisa reconstruir a cada sessão

### O que NÃO fazer
- Não modifique arquivos dentro de `graphify-out/` manualmente
- Não releia o codebase inteiro se o grafo já tem a informação

5. Adicionar ao CLAUDE.md do vault:

## Graphify (Mapas de Codebase)

### Estrutura
- `graphify/projeto-x/` → knowledge graph do projeto X
- Futuros projetos terão subpastas próprias
- Notas geradas automaticamente — NÃO editar manualmente

### No Graph View
- Filtrar por `path:graphify` para ver só nós de código
- Filtrar por `-path:graphify` para esconder nós de código

6. Git Hook (opcional):

Reconstrói o grafo automaticamente a cada commit:

graphify hook install

7. Watch Mode (opcional):

Rebuild automático ao salvar arquivos (rode em terminal separado):

graphify . --watch

Comandos Úteis

Comando	Descrição
`graphify .`	Pipeline completa no diretório atual
`graphify ./src`	Escanear pasta específica
`graphify . --update`	Só processa arquivos modificados
`graphify . --mode deep`	Extração semântica (usa LLM, consome tokens)
`graphify . --watch`	Auto-rebuild ao salvar
`graphify query "pergunta"`	Consultar o grafo diretamente
`open graphify-out/graph.html`	Abrir visualização interativa

Adicionando Novos Projetos

Com vault centralizado, cada projeto é uma subpasta:

cd ~/outro-projeto
graphify . --obsidian --obsidian-dir ~/vault/graphify/outro-projeto

As notas aparecem automaticamente no graph view do Obsidian.

Parte 4 — Fluxo de Trabalho Completo

Sessão típica

Abrir sessão no Claude Code
    │
    ├── /retomar                     ← carrega contexto do vault
    │                                   (últimos logs, decisões, progresso)
    │
    ├── Claude consulta graph.json    ← entende a estrutura do código
    │                                   sem reler todos os arquivos
    │
    ├── Trabalha no código            ← features, bugs, refactors
    │
    ├── /salvar                      ← gera session log no vault
    │
    └── git commit                   ← hook reconstrói o grafo

Economia por camada

Camada	Sem ela	Com ela
`/retomar`	Re-explicar projeto a cada sessão	Claude já sabe o contexto
Graphify	Reler ~40 arquivos (~20k tokens)	Consultar 1 grafo (~280 tokens)
Pipeline de chats	Insights perdidos no histórico	Tudo indexado e buscável
`/salvar` + logs	Esquecer o que foi feito	Histórico com wikilinks

Filtros no Graph View

Filtro	O que mostra
`path:permanent`	Só notas permanentes (conhecimento consolidado)
`path:graphify`	Só nós do codebase (funções, módulos, imports)
`tag:chat-import`	Só chats importados
`-path:graphify -path:chats`	Só notas manuais (vault "puro")

Resultados Reais

Testado em um projeto React + Supabase com 126 arquivos TypeScript:

Métrica	Valor
Nós no grafo	332
Edges (conexões)	258
Comunidades detectadas	124
Tamanho do graph.json	172 KB
Notas Obsidian geradas	456
Redução de tokens por query	499x
Custo LLM da geração	0 tokens (modo AST)
Chats importados no vault	137
Notas permanentes acumuladas	65+
Total de notas no vault	780+

Arquitetura Final

┌─────────────────────────────────────────────────────────────┐
│                    OBSIDIAN VAULT (único)                    │
│                                                             │
│  permanent/  ← conhecimento consolidado (Zettelkasten)      │
│  logs/       ← session logs (/salvar)                       │
│  chats/      ← conversas importadas (pipeline cron)         │
│  graphify/   ← knowledge graphs dos codebases               │
│  projeto-x/  ← MOCs, decisões, arquitetura                  │
│                                                             │
│  CLAUDE.md   ← instruções globais pro Claude Code           │
└─────────────────────────┬───────────────────────────────────┘
                          │
                    Claude Code lê/escreve
                          │
┌─────────────────────────┴───────────────────────────────────┐
│                   REPOSITÓRIO DO PROJETO                     │
│                                                             │
│  src/            ← código-fonte                             │
│  CLAUDE.md       ← instruções + Context Navigation          │
│  graphify-out/   ← graph.json, graph.html, report           │
│  .git/hooks/     ← post-commit reconstrói o grafo           │
└─────────────────────────────────────────────────────────────┘

Troubleshooting

Notas do Graphify não aparecem no Obsidian: Confirme que as notas estão dentro do diretório real do vault. O Obsidian nem sempre aponta para onde você acha — crie uma nota pelo Obsidian e rode find ~ -name "nome.md" para descobrir o path real. Depois mova as notas para lá e faça Cmd+Q / reabra.

Graph view vazio com filtro aplicado: Desative "Orphans" e "Existing files only" nos filtros do graph. Faça Cmd+Q e reabra o Obsidian para forçar reindexação.

Claude Code não consulta o grafo: Verifique se o CLAUDE.md do projeto tem a seção "Context Navigation" e se graphify-out/graph.json existe na raiz do repo.

Cron não roda (macOS): Dê permissão de Full Disk Access ao terminal em Preferências do Sistema → Privacidade e Segurança.

Graphify não gera wiki: A wiki requer edges semânticas. No modo AST-only, use graphify query "pergunta" ou rode --mode deep (consome tokens da API).

Arquivos com parênteses no nome: O Graphify gera notas como minhaFuncao().md. O Obsidian pode ter dificuldades de indexação com () nos nomes. Se necessário, renomeie em batch:

cd ~/vault/graphify/projeto
for f in *"("*; do mv "$f" "$(echo "$f" | sed 's/[()]//g')"; done

Créditos e Links

Graphify — knowledge graph para codebases (MIT)
Obsidian — PKM e second brain (gratuito)
Claude Code — coding agent da Anthropic
Inspirado no sistema de Andrej Karpathy e na comunidade r/ClaudeAI

Se este guia te ajudou, dê uma ⭐ no repo e compartilhe com outros devs que usam Claude Code.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Claude Code + Obsidian + Graphify: O Guia Definitivo para Economia de Tokens e Memória Persistente

Índice

O Problema

A Solução (Visão Geral)

Parte 1 — Obsidian como Memória Persistente

Conceito

Estrutura Recomendada

Setup Passo a Passo

Parte 2 — Pipeline de Importação de Chats

Conceito

Componentes

Setup

Parte 3 — Graphify (Knowledge Graph do Codebase)

Conceito

Setup

Comandos Úteis

Adicionando Novos Projetos

Parte 4 — Fluxo de Trabalho Completo

Sessão típica

Economia por camada

Filtros no Graph View

Resultados Reais

Arquitetura Final

Troubleshooting

Créditos e Links

FilesExpand file tree

README.pt-BR.md

Latest commit

History

README.pt-BR.md

File metadata and controls

Claude Code + Obsidian + Graphify: O Guia Definitivo para Economia de Tokens e Memória Persistente

Índice

O Problema

A Solução (Visão Geral)

Parte 1 — Obsidian como Memória Persistente

Conceito

Estrutura Recomendada

Setup Passo a Passo

Parte 2 — Pipeline de Importação de Chats

Conceito

Componentes

Setup

Parte 3 — Graphify (Knowledge Graph do Codebase)

Conceito

Setup

Comandos Úteis

Adicionando Novos Projetos

Parte 4 — Fluxo de Trabalho Completo

Sessão típica

Economia por camada

Filtros no Graph View

Resultados Reais

Arquitetura Final

Troubleshooting

Créditos e Links