claude-code-memory-setup/README.pt-BR.md

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.

🇺🇸 Read in English

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

1. O Problema
2. A Solução (Visão Geral)
3. Parte 1 — Obsidian como Memória Persistente
4. Parte 2 — Pipeline de Importação de Chats
5. Parte 3 — Graphify (Knowledge Graph do Codebase)
6. Parte 4 — Fluxo de Trabalho Completo
7. Resultados Reais
8. 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 --platform claude

O graphify install --platform claude cria o skill em ~/.claude/skills/graphify/SKILL.md. Outras plataformas também são suportadas (cursor, codex, opencode, etc.).

1.5. Configurar API key (necessário para extração semântica):

O Graphify precisa de uma API key de LLM da Anthropic ou da Moonshot (Kimi) para extração semântica. Exporte uma antes de rodar:

export ANTHROPIC_API_KEY="sua-chave-aqui"
# ou
export MOONSHOT_API_KEY="sua-chave-aqui"

Se quiser pular custos de LLM completamente, use o modo AST-only:

graphify extract . --out ./graphify-out --no-cluster

Isso gera um grafo estrutural sem edges semânticas.

2. Gerar o grafo:

O Graphify tem dois caminhos de execução e as flags --obsidian* originais só funcionam em um deles. Escolha o formato que corresponde a como você está invocando:

A. Dentro do Claude Code (skill — recomendado para este guia):

/graphify . --obsidian --obsidian-dir ~/vault/graphify/nome-do-projeto

Isso roda o slash command /graphify, que o skill em ~/.claude/skills/graphify/SKILL.md interpreta. O skill chama graphify.export.to_obsidian() em Python diretamente, então --obsidian e --obsidian-dir são reconhecidas aqui — elas não fazem parte do parser do shell headless.

B. Do terminal / CI (CLI headless):

graphify extract . --out ./graphify-out

O CLI headless usa subcomandos (extract, update, watch, tree) e não expõe --obsidian / --obsidian-dir / --wiki / --mode deep. Se quiser integração com Obsidian a partir do terminal, faça um symlink do diretório de output para o vault depois da extração:

ln -s $(pwd)/graphify-out ~/vault/graphify/nome-do-projeto/graphify-out

Output gerado (varia conforme o caminho e as flags):

seu-projeto/
└── graphify-out/
    ├── graph.json          # grafo consultável (sempre)
    ├── graph.html          # viz interativa (skill auto-gera; headless: ver passo 3)
    ├── GRAPH_REPORT.md     # god nodes, conexões, métricas (sempre)
    ├── wiki/               # artigos estilo Wikipedia (só skill com --wiki)
    └── cache/              # cache SHA256

~/vault/graphify/nome-do-projeto/    # só quando o skill recebeu --obsidian
    └── (notas Obsidian)              # uma nota por função/módulo

3. Gerar visualização interativa (só no caminho headless):

O skill auto-gera graph.html durante a extração. Para o caminho headless, rode a visualização como passo separado:

graphify tree --graph ./graphify-out/graph.json --output ./graphify-out/GRAPH_TREE.html

Abra o arquivo HTML no navegador para explorar o grafo interativamente.

4. Atualizar .gitignore:

# Graphify
graphify-out/cache/

Mantenha graph.json e GRAPH_REPORT.md versionados.

5. 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)
- Headless: `graphify update .` (só processa arquivos modificados)
- Skill: `/graphify . --update` (mesmo comportamento, rodando via skill — também aceita `--obsidian` para atualizar o vault)
- 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

6. 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

7. Git Hook (opcional):

Reconstrói o grafo automaticamente a cada commit:

graphify hook install

8. Watch Mode (opcional):

Rebuild automático ao salvar arquivos. Escolha o formato conforme como você invoca o graphify.

Headless (terminal separado):

graphify watch .

Skill (dentro do Claude Code):

/graphify . --watch

Comandos Úteis

A tabela abaixo lista os subcomandos do CLI headless que você rodaria no terminal. Dentro do Claude Code, as mesmas operações estão disponíveis via o slash command /graphify documentado em ~/.claude/skills/graphify/SKILL.md — esse formato aceita adicionalmente --obsidian, --obsidian-dir, --wiki e --mode deep (que o parser headless não expõe).

Comando	Descrição
graphify extract .	Extração completa no diretório atual
graphify extract ./src	Escanear pasta específica
graphify update .	Só processa arquivos modificados
graphify watch .	Auto-rebuild ao salvar
graphify query "pergunta"	Consultar o grafo diretamente
graphify explain "NomeDoNo"	Explicação em linguagem natural de um nó
graphify path "A" "B"	Caminho mais curto entre dois nós
graphify tree --graph ./graphify-out/graph.json --output ./graphify-out/GRAPH_TREE.html	Gerar visualização interativa
open graphify-out/graph.html	Abrir visualização interativa (skill gera) ou GRAPH_TREE.html (headless)

Adicionando Novos Projetos

Com vault centralizado, cada projeto é uma subpasta. Mesmos dois caminhos do setup inicial.

Skill (dentro do Claude Code):

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

Headless (terminal):

cd ~/outro-projeto
graphify extract . --out ./graphify-out
ln -s $(pwd)/graphify-out ~/vault/graphify/outro-projeto/graphify-out

Pule a linha do ln -s se você não precisa que o Obsidian enxergue o grafo. As notas aparecem no graph view do Obsidian junto com tudo o mais.

---

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 pasta wiki/ só é produzida pelo formato skill com --wiki (/graphify . --wiki dentro do Claude Code). O subcomando headless graphify extract não expõe --wiki. Do terminal, use graphify query "pergunta" contra o graph.json, ou rode o formato skill se precisar dos artigos estilo Wikipedia.

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.