claude-session-continuity-mcp

Continuidade de sessão com configuração zero para Claude Code. Captura automaticamente o contexto via Claude Hooks, oferece 24 ferramentas para memória, tarefas, soluções e grafo de conhecimento. Pesquisa semântica multilíngue (94+ idiomas).

GitHub

Experimente este MCPPatrocinado

Documentação

passbaton

Continuidade de sessão para agentes de codificação com IA. Seu agente retoma de onde parou — nunca mais reexplique seu projeto. Memória persistente para Claude Code, OpenAI Codex CLI e Google Gemini CLI, compartilhando um único banco de dados local: injeção automática de contexto, transferência em compactação, busca semântica e recuperação de erro→solução. Zero configuração, zero custo de API, 100% local.

⚡ Uma instalação → contexto carregado automaticamente em toda sessão · 🧩 sobrevive à compactação (0 reexplicações) · 🔒 100% local, $0 de API

Session continuity demo — your coding agent auto-restores project context on session start

Renomeado (v2.0.0): este projeto era anteriormente claude-session-continuity-mcp. O nome antigo sugeria que era exclusivo do Claude — nunca foi. Claude Code, Codex CLI e Gemini CLI são todos cidadãos de primeira classe e compartilham uma única memória local. Instalações existentes continuam funcionando: os comandos antigos claude-hook-* ainda são fornecidos como aliases. Consulte Migrando da v1.

O Problema

Toda nova sessão — seja no Claude Code, Codex CLI ou Gemini CLI:

"This is a Next.js 15 project with App Router..."
"We decided to use Server Actions because..."
"Last time we were working on the auth system..."
"The build command is pnpm build..."

5 minutos de configuração de contexto. Toda. Única. Vez.

A Solução

Totalmente automática. Hooks de ciclo de vida cuidam de tudo sem chamadas manuais — no Claude Code, OpenAI Codex CLI e Google Gemini CLI, compartilhando uma única memória local para que o contexto seja transportado entre os três:

# Session start → Auto-loads relevant context + recent session history
# When asking → Auto-injects relevant memories/solutions
# During conversation → Tracks active files + auto-injects error solutions
# On compact → Structured handover context for continuity
# On exit → Extracts commits, decisions, error-fix pairs from transcript

← Auto-output on session start:
# my-app - Session Resumed

📍 **State**: Implementing signup form

## Recent Sessions
### 2026-02-28
**Work**: Completed OAuth integration with Google provider
**Commits**: feat: add OAuth callback handler; fix: redirect URI config
**Decisions**: Use Server Actions instead of API routes

### 2026-02-27
**Work**: Set up authentication foundation
**Next**: Implement signup form validation

## Directives
- 🔴 Always use Zod for form validation
- 📎 Prefer Server Components by default

## Key Memories
- 🎯 Decided on App Router, using Server Actions
- ⚠️ OAuth redirect_uri mismatch → check env file

Zero trabalho manual. O contexto segue você.

Por que isto em vez de outras ferramentas de memória?

A maioria das ferramentas de memória do Claude depende de chamadas explícitas de ferramentas ("lembre disto"), uma API em nuvem ou um worker de IA em segundo plano. Esta é deliberadamente diferente:

	passbaton	MCP típico de nuvem/IA-memória
Configuração	`npm i -g` → hooks instalados automaticamente	Servidor manual + chave de API
Gatilho	5 hooks automáticos (sem comandos)	Você chama uma ferramenta `remember`
Armazenamento	100% SQLite local	Nuvem / serviço externo
Custo de API	$0 — embeddings locais	Por token / assinatura
Latência	< 5ms (no dispositivo)	Viagem de ida e volta pela rede
Privacidade	Nunca sai da sua máquina	Enviado a um provedor
Busca	FTS5 + semântica local, multilíngue KO/EN/JA	Varia

Se você quer memória sem configuração, offline, sem custo, que simplesmente acontece enquanto você trabalha — isto é para você.

Injeção automática vs. busca explícita

Também existe uma ótima classe de ferramentas de busca local (ex.: ctx) que indexam o histórico do seu agente para você consultá-lo (search "failed migration"). Isso é complementar, não é o mesmo trabalho:

	passbaton	Ferramentas de busca local (ctx, etc.)
Como você usa	Automático — o contexto aparece no início da sessão, sem comando	Você (ou o agente) executa uma consulta de busca
Compactação	Hook PreCompact reinjeta uma transferência → 0 contexto reexplicado após uma compactação	Não é sua função (é um índice de busca)
Melhor em	Nunca perder o fio da meada entre sessões e compactações, sem intervenção	Encontrar uma decisão/comando passado específico sob demanda
Cobertura	Claude Code + Codex CLI + Gemini CLI (onde a injeção automática é possível)	Frequentemente 30+ agentes indexados para busca

Use busca quando quiser procurar algo. Use isto quando quiser que seu contexto siga você sem precisar pedir.

Suporte ao Codex CLI (v1.16.0+)

Além do Claude Code, isto também suporta OpenAI Codex CLI. Se ~/.codex existir, o instalador registra os mesmos hooks em ~/.codex/hooks.json (SessionStart, UserPromptSubmit, PreCompact, Stop), e os hooks detectam automaticamente o host e emitem o formato de saída correto (hookSpecificOutput.additionalContext do Codex).

O mesmo sessions.db local é compartilhado, então o contexto é transportado entre ambos os agentes: o que você fez no Codex está disponível no Claude Code e vice-versa.

Escopo: salvar sessão + injeção de contexto funcionam em ambos. O rastreamento de mudanças de arquivo do Codex (PostToolUse) ainda não está conectado — salvar sessão já cobre a maior parte disso via análise de transcrição. O transcript_path do Codex é tratado como uma interface instável (pode ser nulo na inicialização), então a detecção de host usa um marcador --codex injetado pelo instalador em vez de depender do caminho.

Suporte ao Gemini CLI (v1.17.0+)

Também suporta Google Gemini CLI. Se ~/.gemini existir, o instalador registra os hooks em ~/.gemini/settings.json (SessionStart, BeforeAgent, PreCompress, SessionEnd — os nomes de eventos do Gemini), preservando suas outras configurações. Mesmo sessions.db local compartilhado, então o contexto é transportado entre os três agentes.

O formato de transcrição do Gemini foi verificado contra arquivos ~/.gemini/tmp/.../chats/*.jsonl reais — ele usa duas formas (uma linha {type, content} plana e uma linha {"$set":{"messages":[…]}} de diff mais antiga); o analisador lida com ambas. Como no Codex, transcript_path pode ser nulo na inicialização, então a detecção de host usa um marcador --gemini.

Nota honesta de escopo: salvar sessão (SessionEnd) e saída de contexto estão verificados e funcionando. A injeção de contexto SessionStart do Gemini é documentada como apenas consultiva upstream (gemini-cli#15413) — se sua versão do Gemini não renderizar o contexto injetado na inicialização, isso é um limite upstream, não desta ferramenta. A continuidade de sessão ainda funciona via histórico salvo.

Migrando da v1

Se você instalou isto como claude-session-continuity-mcp (v1.x), nada quebra — os comandos claude-hook-* da v1 ainda são fornecidos como aliases na v2.

Para migrar para o novo nome:

npm install -g passbaton          # installs the new package
npm uninstall -g claude-session-continuity-mcp   # optional: drop the old one

O instalador reescreve suas entradas de hook para passbaton-hook-* e remove as linhas antigas claude-hook-* — ele corresponde a ambos os nomes, então você não ficará com duplicatas. Seu sessions.db existente não é tocado: todas as sessões passadas, memórias e soluções são mantidas.

Nada mais muda — mesmos hooks, mesmo banco de dados, mesmo comportamento.

Início Rápido

Requer Node.js 22+. A dependência nativa better-sqlite3 só fornece binários pré-compilados para Node 22, 24 e 26 (as linhas atualmente suportadas — Node 18 e 20 estão ambos em fim de vida). Em Node mais antigo, ele volta a compilar a partir do código-fonte, o que falha sem ferramentas de build. Node 22 e superiores instalam limpo sem necessidade de compilador.

Recomendado: Instalação Global

npm install -g passbaton

É isso! O script pós-instalação automaticamente:

Registra o servidor MCP em ~/.claude.json
Instala os Hooks do Claude em ~/.claude/settings.json

Por que Global (`-g`)?

Esta ferramenta é projetada para rastrear todos os seus projetos do Claude Code em um único banco de dados unificado. A instalação global é fortemente recomendada porque:

Motivo	Detalhe
Fonte única de verdade	Um binário atende a todos os projetos — sem divergência de versões entre projetos
Hooks são por usuário	`~/.claude/settings.json` fica no seu diretório home, não por projeto
Contexto entre projetos	Sessões de `app-a` e `app-b` compartilham o mesmo banco de dados e índice de busca
Uma atualização = tudo atualizado	`npm install -g <latest>` atualiza todos os projetos de uma vez; sem reinstalação por projeto
Hooks resolvem pelo nome do binário	O instalador grava o nome do binário puro (`passbaton-hook-`) quando ele resolve no PATH — o caso normal para `npm i -g`. Medido 135 ms* por disparo vs 1.367 ms para `npm exec -- …` (10×), e o PostToolUse dispara a cada edição. Se o nome não resolver (instalação local), ele volta para `npm exec -- …`

Adicione o banco de dados ao .gitignore do seu projeto. Desde 2.4.0, o passbaton cria <project>/.claude/sessions.db na primeira sessão em qualquer projeto que ele reconhece como raiz de workspace, então um projeto que não tinha banco de dados antes ganhará um:

.claude/sessions.db
.claude/sessions.db-shm
.claude/sessions.db-wal
.claude/*.log

Não ignore todo o .claude/ — o settings.json ali deve ser commitado.

Importante: Mesmo com instalação global, você ainda pode desabilitar o hook para projetos específicos (veja abaixo). Global ≠ forçado em todos os projetos.

Desabilitando Hooks para Projetos Específicos

Instalação global não significa "sempre ativo em todos os lugares". Você tem três camadas de controle:

Camada	Arquivo	Escopo
1. Global ATIVO (padrão)	`~/.claude/settings.json`	Todos os projetos
2. Desligado no projeto inteiro	`<project>/.claude/settings.json`	Time inteiro (commitado)
3. Desligado apenas pessoal	`<project>/.claude/settings.local.json`	Só você (gitignored)

Para desabilitar hooks em um projeto específico, crie o arquivo de substituição com arrays de hooks vazios:

// <project>/.claude/settings.json  (or settings.local.json for personal-only)
{
  "hooks": {
    "SessionStart": [],
    "UserPromptSubmit": [],
    "PostToolUse": [],
    "PreCompact": [],
    "Stop": []
  }
}

Arrays vazios substituem a configuração global → as sessões desse projeto não são mais rastreadas.

Atualizando para uma Nova Versão

npm install -g passbaton@latest

Esse é o único passo — todos os projetos pegam o novo binário no próximo reinício do Claude Code. Sem necessidade de reinstalar em cada projeto.

Alternativa: Instalação Local (Não Recomendada)

Se você realmente quer instalação por projeto (ex.: versão fixada para um projeto):

cd <project> && npm install passbaton

Desvantagem: você precisa instalar separadamente em cada projeto, npm exec pode não encontrar a cópia local de forma confiável a partir do contexto do hook (dependente do cwd), e você paga o custo de inicialização npm exec (~1,4 s) em cada disparo de hook em vez de ~135 ms. Fique com -g a menos que tenha um motivo específico.

O Que É Instalado

Servidor MCP (em ~/.claude.json):

{
  "mcpServers": {
    "project-manager": {
      "command": "npx",
      "args": ["passbaton"]
    }
  }
}

Hooks do Claude (em ~/.claude/settings.json):

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "passbaton-hook-session-start" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "passbaton-hook-user-prompt" }] }],
    "PostToolUse": [{ "matcher": "Edit", "hooks": [{ "type": "command", "command": "passbaton-hook-post-tool" }] }, { "matcher": "Write", "hooks": [{ "type": "command", "command": "passbaton-hook-post-tool" }] }],
    "PreCompact": [{ "hooks": [{ "type": "command", "command": "passbaton-hook-pre-compact" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "passbaton-hook-session-end" }] }]
  }
}

Nota (v2.2.1+): Cobertura completa do ciclo de vida com 5 hooks. O instalador verifica se passbaton-hook-* resolve no PATH e grava o nome puro se sim (≈10× mais rápido por disparo); caso contrário, grava npm exec -- …, que também encontra um node_modules/.bin local.

Hooks Instalados (v1.5.0+)

Hook	Comando	Função
`SessionStart`	`passbaton-hook-session-start`	Carrega automaticamente o contexto do projeto no início da sessão
`UserPromptSubmit`	`passbaton-hook-user-prompt`	Injeta automaticamente memórias relevantes + busca de referência passada
`PostToolUse`	`passbaton-hook-post-tool`	Rastreia arquivos ativos (Edit, Write) + injeta automaticamente soluções de erro (Bash)
`PreCompact`	`passbaton-hook-pre-compact`	Contexto de transferência estruturado antes da compactação
`Stop`	`passbaton-hook-session-end`	Extrai commits, decisões, pares erro-correção da transcrição

Gerenciamento Manual de Hooks

# Check hook status
npx passbaton-hooks status

# Reinstall hooks
npx passbaton-hooks install

# Remove hooks
npx passbaton-hooks uninstall

3. Reinicie o Claude Code

Após a instalação, reinicie o Claude Code para ativar os hooks.

Recursos

Recurso	Descrição
🤖 Zero Trabalho Manual	Os Hooks do Claude automatizam toda captura/carga de contexto
🎯 Apenas Memória de Qualidade	(v1.10.0) Apenas decisões, aprendizados, erros — sem ruído de mudanças de arquivo
🧠 Busca Semântica	Embedding multilingual-e5-small (94+ idiomas, 384d)
🌍 Multilíngue	Coreano/Inglês/Japonês + busca entre idiomas (EN→KR, KR→EN)
🔗 Integração com Git	Mensagens de commit extraídas automaticamente das transcrições
🕸️ Grafo de Conhecimento	Relações de memória (resolve, causa, estende...)
📊 Classificação de Memória	5 tipos: observação, decisão, aprendizado, erro, padrão
✅ Verificação Integrada	Execução de build/teste/lint com um clique
📋 Gerenciamento de Tarefas	Gerenciamento de tarefas baseado em prioridade
🔧 Erro Automático→Solução	(v1.12.0) Erros do Bash detectados automaticamente → injeta soluções passadas; fim de sessão registra automaticamente pares erro-correção
💰 Eficiência de Tokens	(v1.11.0) Removido loadContext do UserPromptSubmit (economiza 24-60K tokens/sessão)
📑 Divulgação Progressiva	(v1.11.0) memory_search retorna índice primeiro, memory_get para conteúdo completo
⏳ Decaimento Temporal	(v1.11.0) Pontuação de memória com meias-vidas específicas por tipo para relevância
📝 Transferência Estruturada	(v1.10.0) PreCompact salva resumo do trabalho, arquivos ativos, ações pendentes
🚪 Fim de Sessão Inteligente	(v1.10.0) Extrai commits, decisões, pares erro-correção da transcrição
🗑️ Limpeza Automática de Ruído	(v1.10.0) Exclui automaticamente memórias de observação obsoletas (3d+)
🔍 Detecção de Referência Passada	(v1.8.0) "저번에 X 어떻게 했어?" busca automaticamente no banco de dados
📝 Extração de Diretrizes do Usuário	(v1.8.0) Extrai automaticamente regras "sempre/nunca" dos prompts

Alternâncias de recursos — tudo é opt-in

(v2.1.0+) Seis comportamentos podem ser ativados/desativados individualmente; os demais são exibidos para transparência, mas estão sempre ativos (a mera existência de um hook é controlada pelo seu settings.json, não pela configuração) ou ainda não conectados. A configuração fica em um arquivo JSON simples e editável manualmente (~/.claude/passbaton.config.json) — separado dos seus dados, portanto sobrevive a um reset do banco de dados. Sem arquivo = padrões atuais (nada muda para usuários existentes).

passbaton config                            # grouped table; ●/○ = toggleable, · = always on
passbaton config set solutionCapture off    # flip a toggleable feature
passbaton config set strictSolutionGate on  # opt into the strict error→fix filter
passbaton config preset minimal             # minimal | default | everything
passbaton config reset                       # back to defaults
passbaton config path                        # print the active config file path

Tentar set um recurso sempre ativo / ainda não conectado é rejeitado com uma mensagem clara. Cada recurso alternável também possui uma variável de ambiente para uso pontual/CI: PASSBATON_<FEATURE>=0 (ex.: PASSBATON_SOLUTIONCAPTURE=0) tem prioridade sobre o arquivo de configuração.

Regra de ativação por padrão: um recurso é lançado ativo somente se for silencioso, seguro e universalmente útil. Qualquer coisa que fale sem ser solicitado, adivinhe ou grave linhas especulativas é lançado desativado.

Legenda: ●/○ = alternável (ativo/desativado) · · = sempre ativo, não é uma alternância de configuração · ⋯ = ainda não conectado.

Núcleo (ativo por padrão)

Recurso	Chave	Alternância	O que faz
Injeção de início de sessão	`sessionStart`	· sempre ativo	Restaura o contexto anterior ao iniciar
Handover de compactação+	`compactionHandover`	● alternável	Antes de uma compactação, carrega seu estado de trabalho mais arquivos quentes e status da última build — a única lacuna que a memória automática da plataforma estruturalmente não cobre
Persistência de sessão	`sessionEnd`	· sempre ativo	Salva o estado da sessão ao sair
Exibição automática de memória	`autoInject`	· sempre ativo	Exibe automaticamente memórias passadas relevantes ao iniciar
Rastreamento de tarefas	`taskTracking`	· sempre ativo	Lê/grava a lista de tarefas via MCP + hooks
Pré-aquecimento de caminho quente	`hotPathPrewarm`	● alternável	Ao iniciar, exibe os arquivos que você mais edita neste projeto, classificados por contagem real de acesso
Registro de verificação	`verificationLedger`	● alternável	Avisa ao iniciar se uma sessão recente deixou a build vermelha ou problemas abertos

sessionStart/sessionEnd são "sempre ativos" porque um hook ou executa ou não — isso é controlado pelo registro do hook em ~/.claude/settings.json, não pela configuração. Para desativá-los, remova o hook lá.

Entre agentes (ativo por padrão)

Recurso	Chave	Alternância	O que faz
Compartilhamento entre agentes	`crossAgentSync`	· inerente	Um único banco de dados local compartilhado entre Claude Code / Codex / Gemini (não é uma alternância — é como o armazenamento funciona)
Captura de uso de ferramentas	`postToolCapture`	· sempre ativo	Observa o uso de ferramentas para construir caminhos quentes (baixo ruído)
Captura de soluções	`solutionCapture`	● alternável	Registra automaticamente pares erro→correção em um arquivo de soluções. Defina desativado para pular completamente (o salvamento da sessão não é afetado)

Experimental (desativado por padrão)

Recurso	Chave	Alternância	O que faz
Portão estrito de soluções	`strictSolutionGate`	○ opt-in	Filtro de captura erro→correção mais estrito — menos entradas de ruído, mas pode descartar algumas reais
Correspondência de gatilhos	`triggerMatching`	⋯ ainda não conectado	(planejado) Corresponder palavras-chave de prompt para injetar soluções automaticamente
Mineração de padrões	`patternMining`	⋯ ainda não conectado	(planejado) Minerar padrões de trabalho e sugerir fluxos de trabalho
Armazenamento automático de memória	`memoryAutoStore`	⋯ ainda não conectado	(planejado) Gravar automaticamente memórias de observação a partir de prompts
Linha de status	`statusLineInject`	⋯ ainda não conectado	(planejado) Anexar uma linha de status passbaton à saída de início de sessão
Rastreamento de hook	`hookTrace`	○ opt-in	Diagnóstico: uma linha por disparo de SessionStart / PostToolUse em `<workspace>/.claude/hook-trace.log`, com `pid` e o `ws_root` resolvido. Desativado por padrão porque PostToolUse dispara a cada edição. Limitado a 5 MB (uma geração mantida). Registra caminhos absolutos de arquivos em texto puro — adicione `.claude/hook-trace.log` ao `.gitignore` se seu repositório rastreia `.claude/`

As únicas flags realmente alternáveis pelo usuário hoje são compactionHandover, hotPathPrewarm, verificationLedger, solutionCapture (ativas) e strictSolutionGate, hookTrace (opt-in).

Ativando hookTrace no Windows: edite ~/.claude/passbaton.config.json (ou execute passbaton config set hookTrace on). A substituição por variável de ambiente PASSBATON_HOOKTRACE=1 também funciona, mas os hooks são iniciados a partir de settings.json via cmd.exe, onde um prefixo VAR=1 command é um erro de sintaxe — então o arquivo de configuração é o caminho prático.

Claude Hooks - Sistema de Contexto Automático

Como Funciona

Hook SessionStart (npx passbaton-hook-session-start):

Detecta automaticamente o projeto: monorepo (apps/project-name/) ou projeto único (package.json nome da pasta raiz)
Carrega contexto de .claude/sessions.db
Injeta: Estado atual, 3 sessões recentes com commits/decisões, diretrizes, tarefas pendentes, memórias-chave filtradas
Limpa automaticamente memórias de ruído antigas (3d+ rastreadas automaticamente, 14d+ compactadas automaticamente)

Hook UserPromptSubmit (npx passbaton-hook-user-prompt):

Executa a cada envio de prompt
(v1.11.0) Não chama mais loadContext() — economiza 24-60K tokens/sessão
Injeta contexto relevante (filtrado: decisões, aprendizados, erros apenas)

Hook PostToolUse (npx passbaton-hook-post-tool):

Rastreia caminhos de arquivos quentes e atualiza active_context.recent_files
(v1.12.0) Detecta automaticamente erros de Bash → pesquisa banco de soluções → injeta soluções passadas no contexto
Não cria mais memórias de observação (v1.10.0 — elimina ruído de [File Change])

Hook PreCompact (npx passbaton-hook-pre-compact):

Constrói contexto de handover estruturado: resumo do trabalho, arquivo ativo, ação pendente, fatos-chave, erros recentes
Não armazena mais memórias de compactação automática (v1.10.0)

Hook Stop (npx passbaton-hook-session-end):

Extrai mensagens de commit da transcrição JSONL (padrões git commit -m)
Extrai pares erro-correção (erro → resolução em até 3 mensagens)
(v1.12.0) Registra automaticamente pares erro→correção na tabela de soluções para reutilização futura
Extrai decisões (padrões "porque", "em vez de", "escolheu")
(v1.11.0) Análise de transcrição em passagem única (4 leituras JSONL → 1)
Armazena metadados estruturados na coluna sessions.issues como JSON

Exemplo de Saída (Início de Sessão)

# my-app - Session Resumed

📍 **State**: Implementing signup form
🚧 **Blocker**: OAuth callback URL issue

## Recent Sessions
### 2026-02-28
**Work**: Completed OAuth integration
**Commits**: feat: add OAuth handler; fix: redirect config
**Decisions**: Use Server Actions over API routes
**Next**: Implement form validation

## Directives
- 🔴 Always use Zod for validation

## Pending Tasks
- 🔄 [P8] Implement form validation
- ⏳ [P5] Add error handling

## Key Memories
- 🎯 Decided on App Router, using Server Actions
- ⚠️ OAuth redirect_uri mismatch → check env file

Gerenciamento de Hooks

# Check status
npx passbaton-hooks status

# Reinstall
npx passbaton-hooks install

# Remove
npx passbaton-hooks uninstall

# Temporarily disable
export MCP_HOOKS_DISABLED=true

Detecção de Referência Passada (v1.8.0)

Quando você pergunta sobre trabalho passado, o hook UserPromptSubmit pesquisa automaticamente no banco de dados:

You: "저번에 인앱결제 어떻게 했어?"
→ Hook detects "저번에" + extracts keyword "인앱결제"
→ Searches sessions, memories (FTS5), and solutions
→ Injects matching results into context automatically

Padrões suportados (coreano e inglês):

Padrão	Exemplo
저번에/전에/이전에 ... 어떻게	"저번에 CORS 에러 어떻게 해결했지?"
~했던/만들었던/해결했던	"수정했던 로그인 로직"
지난 세션/작업에서	"지난 세션에서 결제 구현"
last time/before/previously	"How did we handle auth last time?"
did we/did I ... before	"Did we fix the database migration before?"
remember when/recall when	"Remember when we set up CI?"

Exemplo de saída:

## Related Past Work (auto-detected from your question)

### Sessions
- [2/14] 카카오 로그인 앱키 수정, 인앱결제 IAP 플로우 수정

### Memories
- 🎯 [decision] 테스트: 인앱결제 상품 등록 완료

### Solutions
- **IAP_BILLING_ERROR**: StoreKit 2 migration으로 해결

Por que npm exec? (v1.4.3+)

Versões anteriores usavam caminhos absolutos ou npx:

// v1.3.x - absolute paths (broke on multi-project)
"command": "node \"/path/to/project-a/node_modules/.../session-start.js\""

// v1.4.0-1.4.2 - npx (required global install or hit npm registry)
"command": "npx passbaton-hook-session-start"

Agora usamos npm exec --:

"command": "passbaton-hook-session-start"

npm exec -- encontra o node_modules/.bin local primeiro, depois recorre ao global. Funciona com instalação local e global sem acessar o registro npm.

Ferramentas (API v5) - 25 Ferramentas Focadas

1. Ciclo de Vida da Sessão (4) ⭐

// Start of session - auto-loads context
session_start({ project: "my-app", compact: true })

// End of session - auto-saves context
session_end({
  project: "my-app",
  summary: "Completed auth flow",
  modifiedFiles: ["src/auth.ts", "src/login/page.tsx"]
})

// View session history
session_history({ project: "my-app", limit: 5 })

// Semantic search past sessions
search_sessions({ query: "auth work", project: "my-app" })

2. Gerenciamento de Projetos (4)

// Get project status with task stats
project_status({ project: "my-app" })

// Initialize new project
project_init({ project: "my-app" })

// Analyze project tech stack
project_analyze({ project: "my-app" })

// List all projects
list_projects()

3. Gerenciamento de Tarefas (4)

// Add a task
task_add({ project: "my-app", title: "Implement signup", priority: 8 })

// Update task status
task_update({ taskId: 1, status: "done" })

// List tasks
task_list({ project: "my-app", status: "pending" })

// Suggest tasks from TODO comments
task_suggest({ project: "my-app" })

4. Arquivo de Soluções (3)

// Record an error solution
solution_record({
  errorSignature: "TypeError: Cannot read property 'id'",
  solution: "Use optional chaining: user?.id"
})

// Find similar solutions (keyword or semantic)
solution_find({ query: "TypeError property", semantic: true })

// AI-powered solution suggestion
solution_suggest({ errorMessage: "Cannot read property 'email'" })

5. Verificação (3)

// Run build
verify_build({ project: "my-app" })

// Run tests
verify_test({ project: "my-app" })

// Run all (build + test + lint)
verify_all({ project: "my-app" })

6. Sistema de Memória (5)

// Store a classified memory
memory_store({
  content: "State management with Riverpod makes testing easier",
  type: "learning",  // observation, decision, learning, error, pattern
  project: "my-app",
  tags: ["flutter", "state-management"],
  importance: 8,
  relatedTo: 23  // Connect to existing memory
})

// Search memories — returns index (id, type, tags, score) for token efficiency
memory_search({
  query: "state management test",
  type: "learning",
  semantic: true,  // Use embedding similarity
  limit: 10
})

// Get full memory content by ID (v1.11.0)
memory_get({ memoryId: 23 })

// Find related memories (graph + semantic)
memory_related({
  memoryId: 23,
  includeGraph: true,
  includeSemantic: true
})

// Get memory statistics
memory_stats({ project: "my-app" })

7. Grafo de Conhecimento (2)

// Connect two memories with a typed relation
graph_connect({
  sourceId: 23,
  targetId: 25,
  relation: "solves",  // related_to, causes, solves, depends_on, contradicts, extends, example_of
  strength: 0.9
})

// Explore knowledge graph
graph_explore({
  memoryId: 23,
  depth: 2,
  relation: "all",  // or specific relation type
  direction: "both"  // outgoing, incoming, both
})

Tipos de Memória

Tipo	Descrição	Caso de Uso
`observation`	Padrões, estruturas encontradas no código	"Todas as telas estão separadas na pasta features/"
`decision`	Arquitetura, escolhas de bibliotecas	"Decidimos usar SharedPreferences para cache"
`learning`	Novo conhecimento, melhores práticas	"Riverpod é melhor para testes"
`error`	Erros ocorridos e soluções	"Provider.read() não reconstrói → use watch()"
`pattern`	Padrões de código recorrentes, convenções	"Evite abuso da palavra-chave late"

Tipos de Relação

Relação	Descrição	Exemplo
`related_to`	Relação geral	A e B estão relacionados
`causes`	A causa B	Decisão de cache → mudança na estrutura de pastas
`solves`	A resolve B	Aprendizado de Riverpod → correção de bug de Provider
`depends_on`	A depende de B	Estrutura de pastas → Decisão de cache
`contradicts`	A conflita com B	Duas decisões de design conflitam
`extends`	A estende B	Padrão late → Estendido para aprendizado de Riverpod
`example_of`	A é exemplo de B	Código específico é exemplo de padrão

Armazenamento de Dados

Banco de dados SQLite em ~/.claude/sessions.db:

Tabela	Finalidade
`memories`	Memórias classificadas (observação, decisão, aprendizado, erro, padrão)
`memories_fts`	Índice de busca em texto completo (FTS5)
`memory_relations`	Relações do grafo de conhecimento
`embeddings_v4`	Vetores de busca semântica (multilingual-e5-small, 384d)
`project_context`	Informações fixas do projeto (stack de tecnologia, decisões)
`active_context`	Estado atual do trabalho
`tasks`	Backlog de tarefas
`solutions`	Arquivo de soluções de erros
`sessions`	Histórico de sessões

Variáveis de Ambiente

Variável	Padrão	Descrição
`WORKSPACE_ROOT`	-	Caminho raiz do workspace (obrigatório)
`MCP_HOOKS_DISABLED`	`false`	Desativar Claude Hooks
`LOG_LEVEL`	`info`	Nível de log (debug/info/warn/error)
`LOG_FILE`	-	Caminho opcional de log em arquivo

Desenvolvimento

# Clone
git clone https://github.com/leesgit/passbaton.git
cd passbaton

# Install
npm install

# Build
npm run build

# Test
npm test

# Test with coverage
npm run test:coverage

Desempenho

Métrica	Valor
Carregamento de contexto (em cache)	<5ms
Busca de memória (FTS)	~10ms
Busca semântica	~50ms
Verificação de build	Depende do projeto

Roadmap

Contribuindo

PRs são bem-vindos! Por favor:

Faça um fork do repositório
Crie um branch de funcionalidade
Adicione testes para novos recursos
Garanta que npm test passe
Envie um PR

Licença

Agradecimentos

Model Context Protocol por Anthropic
Xenova Transformers para embeddings

Se isso poupar você de ter que reexplicar seu projeto, considere dar uma ⭐ — isso realmente ajuda outras pessoas a encontrá-lo.