Início Rápido: Instalação e Configuração

O Que Você Vai Aprender

Nesta lição, você aprenderá:

Instalar o plugin opencode-supermemory em seu ambiente OpenCode.
Configurar a Supermemory API Key para conectar ao banco de memória na nuvem.
Verificar se o plugin foi carregado com sucesso.
Resolver conflitos potenciais com outros plugins (como o Oh My OpenCode).

Após completar, seu Agent terá a capacidade básica de conectar ao banco de memória na nuvem.

Seu Problema Atual

Você pode ter percebido que, embora o Agent do OpenCode seja inteligente, ele é muito esquecido:

Cada vez que inicia uma nova sessão, ele parece ter perdido a memória e não se lembra de suas preferências anteriores.
Você ensinou-lhe padrões de arquitetura no projeto A, mas no projeto B ele esqueceu.
Em sessões longas, informações importantes anteriores são "expulsas" do contexto.

Você precisa de um cérebro externo para ajudar o Agent a lembrar essas coisas.

Quando Usar Esta Abordagem

Primeira vez: Quando você está começando a usar o opencode-supermemory.
Reinstalação: Quando você migra para um novo computador ou redefiniu a configuração do OpenCode.
Solução de problemas: Quando você suspeita que o plugin não foi instalado corretamente ou há problemas de conexão da API.

🎒 Preparação Antes de Começar

Antes de começar, certifique-se de que você já:

Instalou o OpenCode: Certifique-se de que o comando opencode está disponível no terminal.
Obteve a API Key:
- Visite o Supermemory Console
- Registre-se/faca login na conta
- Crie uma nova API Key (começa com sm_)

O que é Supermemory?

Supermemory é uma camada de memória na nuvem projetada especificamente para AI Agent. Não apenas armazena dados, mas também ajuda o Agent a lembrar da coisa certa no momento certo por meio de busca semântica.

Ideia Central

O processo de instalação é muito simples, essencialmente três passos:

Instalar o plugin: Execute o script de instalação, registre o plugin no OpenCode.
Configurar a chave: Diga ao plugin qual é a sua API Key.
Verificar a conexão: Reinicie o OpenCode, confirme que o Agent consegue ver as novas ferramentas.

Siga-me

Passo 1: Instalar o Plugin

Fornecemos dois métodos de instalação, escolha o que melhor lhe convier.

Sou Humano (instalação interativa)Sou Agent (instalação automática)

bash

# Recomendado: terá orientação interativa, ajudando você a lidar automaticamente com a configuração
bunx opencode-supermemory@latest install

bash

# Se você estiver pedindo ao Agent para instalar, use este comando (pula confirmação interativa e resolve automaticamente conflitos)
bunx opencode-supermemory@latest install --no-tui --disable-context-recovery

Você deve ver: Saída do terminal ✓ Setup complete!, indicando que o plugin foi registrado com sucesso em ~/.config/opencode/opencode.jsonc.

Passo 2: Configurar a API Key

O plugin precisa da API Key para ler e gravar sua memória na nuvem. Você tem duas formas de configurar:

Método A: Variável de Ambiente (Recomendado)

Adicione diretamente ao seu arquivo de configuração Shell (como .zshrc ou .bashrc):

bash

export SUPERMEMORY_API_KEY="sm_sua-chave..."

Método B: Arquivo de Configuração

Ou crie um arquivo de configuração dedicado ~/.config/opencode/supermemory.jsonc:

json

{
  "apiKey": "sm_sua-chave..."
}

Por que: Variáveis de ambiente são mais seguras e não são comprometidas acidentalmente para o repositório de código; arquivos de configuração são mais convenientes para gerenciar múltiplas configurações.

Passo 3: Resolver Conflitos (se você usa o Oh My OpenCode)

Se você instalou o Oh My OpenCode, sua funcionalidade de gerenciamento de contexto pode entrar em conflito com o Supermemory.

Como verificar: O script de instalação geralmente detecta e solicita automaticamente desabilitar hooks conflitantes. Se não, verifique manualmente ~/.config/opencode/oh-my-opencode.json:

json

{
  "disabled_hooks": [
    "anthropic-context-window-limit-recovery"  // ✅ Certifique-se de que esta linha existe
  ]
}

Por que: O Supermemory fornece "compactação preemptiva" (Preemptive Compaction) mais inteligente; se dois plugins tentam gerenciar o contexto simultaneamente, isso causará confusão.

Passo 4: Verificar a Instalação

Reinicie o OpenCode e execute o comando de verificação:

bash

opencode -c

Ou entre diretamente no modo interativo do OpenCode e visualize a lista de ferramentas.

Você deve ver: Na lista de ferramentas (Tools), aparece a ferramenta supermemory.

Available Tools:
- supermemory (add, search, profile, list, forget)
...

Ponto de Verificação ✅

Verifique os seguintes itens para garantir que tudo esteja pronto:

[ ] Execute cat ~/.config/opencode/opencode.jsonc, você pode ver "opencode-supermemory" na lista de plugin.
[ ] A variável de ambiente SUPERMEMORY_API_KEY está em vigor (verifique com echo $SUPERMEMORY_API_KEY).
[ ] Após executar opencode, o Agent não relata erros.

Avisos sobre Armadilhas

Erro Comum: API Key não está em vigor

Se você configurou a variável de ambiente mas o plugin indica não autenticado, verifique:

Você reiniciou o terminal? (após modificar .zshrc, você precisa de source ~/.zshrc ou reiniciar)
Você reiniciou o OpenCode? (o processo OpenCode precisa ser reiniciado para ler novas variáveis)

Erro Comum: Erro de formato JSON

Se você modificar manualmente opencode.jsonc, certifique-se de que o formato JSON está correto (especialmente vírgulas). O script de instalação lida com isso automaticamente, mas modificações manuais são propensas a erros.

Resumo da Lição

Parabéns! Você instalou com sucesso "hipocampo" para o OpenCode. Agora seu Agent está pronto para começar a memorizar.

Instalamos o plugin opencode-supermemory.
Configuramos as credenciais de conexão à nuvem.
Excluímos conflitos potenciais de plugins.

Próxima Lição

Próxima lição: Inicialização do Projeto: Estabeleça a Primeira Impressão.
Você aprenderá:
Como fazer com que o Agent faça uma varredura profunda de todo o projeto com um comando.
Como fazer com que o Agent lembre da arquitetura, stack tecnológico e regras implícitas do projeto.
Como ver exatamente o que o Agent lembrou.

Apêndice: Referência de Código-fonte

Clique para expandir e ver a localização do código-fonte

Última atualização: 2026-01-23

Funcionalidade	Caminho do Arquivo	Linha
Lógica do script de instalação	`src/cli.ts`	327-410
Lógica de registro do plugin	`src/cli.ts`	195-248
Lógica de detecção de conflitos	`src/cli.ts`	273-320
Carregamento do arquivo de configuração	`src/config.ts`	-

Início Rápido

Recursos Principais

Recursos Avançados

Segurança

Início Rápido: Instalação e Configuração

O Que Você Vai Aprender

Seu Problema Atual

Quando Usar Esta Abordagem

🎒 Preparação Antes de Começar

Ideia Central

Siga-me

Passo 1: Instalar o Plugin

Passo 2: Configurar a API Key

Método A: Variável de Ambiente (Recomendado)

Método B: Arquivo de Configuração

Passo 3: Resolver Conflitos (se você usa o Oh My OpenCode)

Passo 4: Verificar a Instalação

Ponto de Verificação ✅

Avisos sobre Armadilhas

Resumo da Lição

Próxima Lição

Apêndice: Referência de Código-fonte

Início Rápido: Instalação e Configuração ​

O Que Você Vai Aprender ​

Seu Problema Atual ​

Quando Usar Esta Abordagem ​

🎒 Preparação Antes de Começar ​

Ideia Central ​

Siga-me ​

Passo 1: Instalar o Plugin ​

Passo 2: Configurar a API Key ​

Método A: Variável de Ambiente (Recomendado) ​

Método B: Arquivo de Configuração ​

Passo 3: Resolver Conflitos (se você usa o Oh My OpenCode) ​

Passo 4: Verificar a Instalação ​

Ponto de Verificação ✅ ​

Avisos sobre Armadilhas ​

Resumo da Lição ​

Próxima Lição ​

Apêndice: Referência de Código-fonte ​

Início Rápido: Instalação e Configuração

O Que Você Vai Aprender

Seu Problema Atual

Quando Usar Esta Abordagem

🎒 Preparação Antes de Começar

Ideia Central

Siga-me

Passo 1: Instalar o Plugin

Passo 2: Configurar a API Key

Método A: Variável de Ambiente (Recomendado)

Método B: Arquivo de Configuração

Passo 3: Resolver Conflitos (se você usa o Oh My OpenCode)

Passo 4: Verificar a Instalação

Ponto de Verificação ✅

Avisos sobre Armadilhas

Resumo da Lição

Próxima Lição

Apêndice: Referência de Código-fonte