AgentMemory

Camada de memória nativa do MCP para Claude Code, Cursor, Cline, Continue e outras 16 ferramentas de IA. Busca híbrida (BM25 + pgvector + graph), auto-hospedada no Supabase + Vercel, 100% MIT, sem paywall.

GitHub

Experimente este MCPPatrocinado

Documentação

AgentMemory.fyi

Gerenciador visual de memória para agentes de IA. Fonte única de verdade para Claude Code, Cursor, Cline, Continue.

_{* Preview hospedada na Vercel — entre com e-mail ou GitHub para testar. Seus dados permanecem privados na sua conta via Supabase RLS. Para auto-hospedagem ou modo somente local, veja Início rápido abaixo.}

Capturas de tela

Dashboard

Dashboard — estatísticas gerais, memórias recentes, divisão por categoria e ações rápidas

Memory Graph

Grafo de Memória — visualização de força direcionada D3 com painel de Detalhes da Memória e Memórias Semelhantes (98% / 97% de correspondência) classificadas por distância vetorial

Export

Exportação — CLAUDE.md, .cursorrules, MemGPT JSON ou URL somente leitura compartilhável com um clique, com pré-visualização ao vivo e filtros por categoria

100% gratuito, para sempre

AgentMemory é open source sob licença MIT. Sem paywalls, sem níveis premium, sem limites.

Gratuito para todos — memórias ilimitadas, projetos ilimitados
Auto-hospedável — execute localmente para sempre, sem telemetria, sem aprisionamento
Nativo MCP — funciona como servidor Model Context Protocol no Claude Desktop, Cursor, Cline, Continue, Windsurf, Roo Code, Kilo Code, Zed, Aider, Goose, Warp, Codex CLI, Gemini CLI, GitHub Copilot CLI, Qwen Code CLI, Google Antigravity, AWS Kiro, Droid, OpenCode, OpenClaw e pi-mono. Veja Conecte à sua ferramenta de IA abaixo.
Visual — visualização em grafo de todas as memórias e suas relações semânticas
Portátil — importação/exportação para .cursorrules, CLAUDE.md, MemGPT JSON, sessões .jsonl do Claude Code
Sincronização em nuvem opcional — entre para sincronizar suas memórias entre dispositivos via Supabase

Apoie o projeto

AgentMemory é construído e mantido no tempo livre. Se ele economiza seu tempo, considere apoiar o desenvolvimento:

Doe no DonationAlerts — cartões, SBP, YooMoney, cripto, 100+ métodos
Dê uma estrela no repositório — a melhor doação de $0
Reporte bugs ou solicite recursos
Contribua com PRs
Divulgue no Twitter / Reddit / HackerNews

Início rápido

Interface web (modo somente local)

npm install
npm run dev
# → http://localhost:5173

Funciona sem backend. As memórias são armazenadas em localStorage (navegador) ou ~/.agentmemory/ (stdio MCP).

Servidor MCP (stdio, local)

npm run mcp

Configura em claude_desktop_config.json (o script executa mcp/index.ts via tsx — sem etapa de build):

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

9 ferramentas: add_memory, search_memories, list_memories, find_similar, delete_memory, list_projects, switch_project, get_project_context, import_jsonl, backfill_embeddings. 3 recursos: agentmemory://rules, agentmemory://graph, agentmemory://projects. 100% gratuito, sem chaves de licença.

Conecte à sua ferramenta de IA

AgentMemory expõe o mesmo servidor MCP em dois modos:

stdio local — executa mcp/index.ts via tsx; o processo do agente o invoca como processo filho. Melhor para ferramentas de desktop que têm acesso ao sistema de arquivos da sua máquina.
HTTP em nuvem — endpoint HTTP Streamable em https://<your-host>/mcp (padrão Vercel). Melhor para ferramentas hospedadas, clientes web e compartilhamento da mesma memória entre máquinas. O JWT do Supabase do usuário vai em Authorization: Bearer <jwt>.

Os trechos abaixo assumem que seu clone está em /absolute/path/to/agentmemory. O comando stdio local executa o servidor MCP diretamente com tsx — sem necessidade de etapa de build.

Dois trechos de referência que você reutilizará

// LOCAL — stdio
{
  "command": "npx",
  "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
  "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
}

// CLOUD — HTTP
{
  "url": "https://your-app.vercel.app/mcp",
  "headers": { "Authorization": "Bearer <supabase-jwt>" }
}

Para obter um JWT do Supabase, entre na interface web hospedada do AgentMemory, depois no DevTools execute JSON.parse(localStorage.getItem('sb-<project>-auth-token') || 'null') e copie access_token. Os JWTs duram ~1h; atualize executando o comando novamente após cada sessão.

Índice

#	Ferramenta	Arquivo de configuração	Modo
1	Claude Desktop	`claude_desktop_config.json`	stdio / http
2	Cursor	`.cursor/mcp.json`	stdio / http
3	Cline	Barra lateral Cline → MCP Servers	stdio / http
4	Continue	`~/.continue/config.yaml`	stdio / http
5	Roo Code	`.roo/mcp.json`	stdio / http
6	Kilo Code	Barra lateral Kilo → MCP Servers	stdio / http
7	Windsurf	`~/.codeium/windsurf/mcp_config.json`	stdio / http
8	Zed	`~/.config/zed/settings.json`	stdio / http
9	Aider	flag `--mcp-server`	stdio
10	Goose	`~/.config/goose/config.yaml`	stdio / http
11	Warp	Warp Drive → MCP Servers	stdio / http
12	OpenAI Codex CLI	`~/.codex/config.toml`	stdio / http
13	Google Gemini CLI	`~/.gemini/settings.json`	stdio / http
14	GitHub Copilot CLI	`~/.config/github-copilot/mcp.json`	stdio / http
15	Qwen Code CLI	`~/.qwen/settings.json`	stdio / http
16	Google Antigravity	`.antigravity/mcp.json`	stdio / http
17	AWS Kiro	`.kiro/settings/mcp.json`	stdio / http
18	Droid (Factory)	`~/.droid/mcp.json`	stdio / http
19	OpenCode	`opencode.json` / `~/.config/opencode/config.json`	stdio / http
20	OpenClaw & pi-mono	`~/.openclaw/openclaw.json` / `~/.pi/config.json`	stdio / http

1. Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (mac) · %APPDATA%\Claude\claude_desktop_config.json (win) · ~/.config/Claude/claude_desktop_config.json (linux).

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

Reinicie o Claude Desktop. O painel de conectores deve mostrar 9 🔧 ferramentas e 3 📄 recursos.

2. Cursor

.cursor/mcp.json no seu workspace (por projeto) ou ~/.cursor/mcp.json (global).

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

Cursor Settings → Features → MCP. Clique em Refresh se o servidor não aparecer.

3. Cline

Extensão do VSCode. Abra a barra lateral do Cline → ⚙️ Settings → MCP Servers → Configure MCP Servers → edite cline_mcp_settings.json:

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" },
      "disabled": false
    }
  }
}

O Cline recarrega o arquivo automaticamente ao salvar. As ferramentas de memória aparecem sob o ícone 🔧 no chat.

4. Continue

~/.continue/config.yaml (YAML; Continue 1.0+):

mcpServers:
  - name: agentmemory
    command: npx
    args:
      - tsx
      - /absolute/path/to/agentmemory/mcp/index.ts
    env:
      AGENTMEMORY_HOME: /absolute/path/to/storage

Para modo nuvem, substitua por transport: http + url + headers (veja documentação MCP do Continue).

5. Roo Code

.roo/mcp.json no seu workspace, ou via barra lateral Roo → MCP → Edit Global MCP:

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

6. Kilo Code

Kilo é um fork do OpenCode, então o mesmo esquema funciona. Abra a barra lateral Kilo → MCP Servers → Edit Global MCP, ou .kilocode/mcp.json no seu workspace:

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

Para modo nuvem, troque a entrada por { "url": "https://...", "headers": { "Authorization": "Bearer ..." } }.

7. Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

Windsurf Settings → Cascade → MCP Servers mostra após reiniciar.

8. Zed

~/.config/zed/settings.json (nota: Zed usa context_servers, não mcpServers):

{
  "context_servers": {
    "agentmemory": {
      "command": {
        "path": "npx",
        "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
        "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
      }
    }
  }
}

Para modo nuvem, use "settings": { "url": "https://...", "headers": { "Authorization": "Bearer ..." } } em vez de command. Veja documentação de servidores de contexto do Zed.

9. Aider

Aider 0.73+ adicionou MCP. Passe o servidor na linha de comando (um --mcp-server por servidor):

aider --mcp-server "npx tsx /absolute/path/to/agentmemory/mcp/index.ts AGENTMEMORY_HOME=/path/to/storage"

Ou em ~/.aider.conf.yml:

mcp-servers: |
  agentmemory: npx tsx /absolute/path/to/agentmemory/mcp/index.ts AGENTMEMORY_HOME=/path/to/storage

O Aider lista as ferramentas disponíveis na inicialização; referencie-as no chat com /tool agentmemory__add_memory ....

10. Goose

~/.config/goose/config.yaml — extensions é o termo do Goose para servidores MCP:

extensions:
  agentmemory:
    type: stdio
    cmd: npx
    args: ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"]
    envs:
      AGENTMEMORY_HOME: /absolute/path/to/storage
    enabled: true

Modo nuvem: defina type: streamable_http, uri: https://your-app.vercel.app/mcp, headers.Authorization: "Bearer <jwt>", envs: {}.

11. Warp

Warp Drive → Settings → AI → Manage MCP Servers → + Add:

Campo	Valor
Nome	`agentmemory`
Comando	`npx tsx /absolute/path/to/agentmemory/mcp/index.ts`
Env	`AGENTMEMORY_HOME=/absolute/path/to/storage`

O Warp também suporta ~/.warp/mcp_config.json para sincronização entre máquinas — mesmo esquema mcpServers do Claude Desktop.

12. OpenAI Codex CLI

~/.codex/config.toml:

[mcp_servers.agentmemory]
command = "npx"
args = ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"]
env = { AGENTMEMORY_HOME = "/absolute/path/to/storage" }

Para nuvem, troque a tabela por:

[mcp_servers.agentmemory]
url = "https://your-app.vercel.app/mcp"
http_headers = { Authorization = "Bearer <supabase-jwt>" }

Verifique com codex mcp list.

13. Google Gemini CLI

~/.gemini/settings.json:

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

Confiável por padrão se trust: true estiver definido por servidor. Veja documentação MCP do Gemini CLI.

14. GitHub Copilot CLI

O novo CLI copilot (substitui o antigo gh copilot). ~/.config/github-copilot/mcp.json:

{
  "mcpServers": {
    "agentmemory": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

Ou inline em tempo de execução: copilot --additional-mcp-config @/absolute/path/to/config.json. As ferramentas são prefixadas automaticamente com agentmemory__ no chat.

15. Qwen Code CLI

CLI qwen da Alibaba (Qwen3-Coder). ~/.qwen/settings.json (ou ~/.qwen-cli/settings.json dependendo do build):

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

16. Google Antigravity

.antigravity/mcp.json no seu workspace (por projeto) ou ~/.antigravity/mcp.json (global):

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

Modo nuvem: substitua por { "url": "https://your-app.vercel.app/mcp", "headers": { "Authorization": "Bearer <supabase-jwt>" } }. O Antigravity capta o arquivo ao abrir o workspace.

17. AWS Kiro

.kiro/settings/mcp.json no seu workspace (por projeto) ou ~/.kiro/settings/mcp.json (global):

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

Kiro Settings → MCP Servers mostra um botão de atualização se o servidor estiver inacessível.

18. Droid (Factory)

~/.droid/mcp.json (global) ou .factory/mcp.json (por projeto):

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

Execute droid mcp list para verificar se carregou. No TUI, use @agentmemory para invocar ferramentas.

19. OpenCode

opencode.json na raiz do seu projeto, ou ~/.config/opencode/config.json para global:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agentmemory": {
      "type": "local",
      "command": ["npx", "tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "environment": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" },
      "enabled": true
    }
  }
}

Para modo nuvem, troque para "type": "remote", "url": "https://your-app.vercel.app/mcp", "headers": { "Authorization": "Bearer <supabase-jwt>" }. Referencie em prompts com use the agentmemory tool.

20. OpenClaw & pi-mono

Estes são assistentes pessoais de IA, não IDEs de codificação — eles aceitam servidores MCP como skills, então AgentMemory se torna a memória de longo prazo do assistente.

OpenClaw — ~/.openclaw/openclaw.json:

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

Reinicie o gateway com openclaw gateway restart. No Telegram/WhatsApp/Discord, o assistente agora tem memória persistente entre sessões — diga "lembre que eu prefiro modo escuro" e ele guarda.

pi-mono (CLI pi por Mario Zechner) — ~/.pi/config.json:

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

Execute pi e peça ao agente para search_memories para contexto anterior.

Solução de problemas

Sintoma	Correção
`ENOENT` em `mcp/index.ts`	Use um caminho absoluto; `~` não expande dentro do JSON
`command not found: tsx`	`npm i -g tsx`, ou substitua `npx tsx` por `node --import tsx`
Ferramentas nunca aparecem	Reinicie o cliente. Alguns (Cline, Kilo, Roo) precisam de alternância explícita de "ativar"
`401 Unauthorized` na nuvem	JWT expirado; copie novamente do DevTools da interface web `localStorage`
`429 Too Many Requests` na nuvem	Atingiu `RATE_LIMIT_PER_HOUR`; aguarde ou reduza via `backfill_embeddings`
`Cannot find module '@modelcontextprotocol/...'`	`npm install` na raiz do repositório agentmemory

Recursos

Decaimento de memória e rastreamento de acesso

As memórias seguem uma curva de decaimento exponencial (strength = 0.5^(days/30) × importance/5) e recebem um impulso toda vez que são lidas. Cada memória se enquadra em um dos quatro níveis, exibidos como um selo colorido no cartão:

Nível	Força	Cor	Significado
quente	≥ 0.70	vermelho	Criada recentemente ou acessada com frequência
morno	≥ 0.40	âmbar	Ainda relevante
frio	≥ 0.15	azul	Desvanecendo, mas mantida para contexto
morto	< 0.15	cinza	Candidata automática para esquecimento

runAutoForget() roda na inicialização do aplicativo e remove memórias que correspondem a qualquer um dos: TTL expirado, OU (strength < 0.05 AND access_count < 3), OU (importance ≤ 2 AND age > 180 days).
MemoryCard chama touchMemory(id) na montagem, incrementando access_count e atualizando last_accessed_at.
Funciona em todos os backends: local (zustand), Supabase (coluna strength do Postgres + runAutoForget de useAuth).

Busca híbrida (BM25 + Vetor + Grafo via RRF)

Três fontes se fundem via Fusão por Classificação Recíproca (k=60) em src/utils/rrf.ts:

Fonte	Peso	Onde roda	Implementação
Vetor (cosseno)	0.6	Servidor (nuvem) / local	pgvector + HuggingFace Inference API, 384-dim MiniLM-L6-v2 (grátis, sem cartão de crédito)
BM25	0.4	Ambos	similaridade de trigramas pg_trgm (servidor) ou índice invertido com stemmer de Porter (local)
Grafo	0.3	Ambos	expansão de 1 salto através da tabela `relations` (servidor) ou arestas em memória (local)

Os melhores resultados de cada fonte são unidos com RRF(d) = Σᵢ wᵢ / (k + rankᵢ(d)) e os top-N são retornados. O índice BM25 local armazena em cache por (count, max(updated_at)) e invalida a cada adição/atualização/exclusão/esquecimento automático.

Habilitando busca semântica no MCP na nuvem — cadastre-se em huggingface.co (grátis), pegue um token de leitura em https://huggingface.co/settings/tokens e defina HUGGINGFACE_API_KEY na Vercel. O handler serverless em api/mcp.ts instancia createHuggingFaceEmbedder(token) e o injeta no SupabaseBackend. Em add_memory o conteúdo é incorporado e armazenado como vector(384); em search_memories a consulta é incorporada e o RPC semantic_search_memories faz busca por cosseno via índice HNSW.

Sem a chave, o servidor ainda funciona — ele apenas ignora a fonte vetorial e o RRF se torna bidirecional (BM25 + grafo).

Preenchendo memórias antigas — após habilitar o incorporador, as linhas existentes têm embedding = NULL. Execute a ferramenta MCP backfill_embeddings repetidamente até remaining = 0:

backfill_embeddings({ limit: 64 })
backfill_embeddings({ limit: 64 })
…

Cada chamada custa ⌈N/32⌉ chamadas de API de incorporação e respeita o limite de taxa por usuário. O timeout serverless de 60s comporta ~3 lotes HF = ~96 memórias por invocação.

Limite de taxa — o esquema do Supabase adiciona uma tabela api_rate_limits e um RPC consume_rate_limit(p_user_id, p_cost, p_max). Cada chamada de incorporação (consulta de busca, inserção de memória, lote de preenchimento) consome atomicamente ceil(texts/32) unidades de uma janela deslizante de 1 hora. O limite padrão é RATE_LIMIT_PER_HOUR=100, o que deixa bastante margem no nível gratuito de 30k/mês da HF para ~30 usuários ativos. Defina a env para 0 para desativar. Se você atingir o limite, a chamada MCP retorna isError: true com o timestamp exato de redefinição.

Importação JSONL de sessões do Claude Code

Arraste um arquivo de sessão do Claude Code (~/.claude/projects/-my-project/<uuid>.jsonl) para a página de importação, ou chame a ferramenta MCP import_jsonl. O parser:

Lê um objeto JSON por linha
Descarta blocos tool_use / tool_result (mantém apenas mensagens user / assistant)
Filtra mensagens do usuário: 20–600 caracteres, descarta lembretes do sistema e comandos de shell (ok, ./run-build.sh, etc.)
Categoriza automaticamente com dicas de regex: decision > constraint > preference > architecture > context (padrão)
Extrai tags de #hashtags e dicas de extensão de arquivo (*.ts → typescript)
Limita a 200 memórias por arquivo

Uso do MCP (funciona nos modos stdio e HTTP):

{
  "name": "import_jsonl",
  "arguments": {
    "path": "/Users/you/.claude/projects/-my-project/abc123.jsonl"
  }
}

Retorna { imported: N, total: M, user_messages: K, accepted: K }.

Sincronização na nuvem (Supabase + Vercel)

Execute seu próprio backend de sincronização privado em ~5 minutos.

1. Crie um projeto Supabase

Vá para supabase.com → Novo projeto
Depois de provisionado, abra Editor SQL → cole o conteúdo de supabase/schema.sql → Executar
- O esquema habilita a extensão pgvector e cria a coluna embedding vector(384) + índice HNSW na primeira execução
Em Autenticação → Provedores, habilite Email (link mágico) e GitHub (opcional — veja §1a abaixo para passo a passo)
Em Configurações → API, copie sua Project URL e chave anon
(Opcional, para busca semântica) Cadastre-se em huggingface.co e crie um token de leitura em https://huggingface.co/settings/tokens

1a. Habilite o login do GitHub (opcional)

O login do GitHub é um clique na página de autenticação e permite que você evite a ida e volta do link mágico por email. A configuração leva ~5 minutos.

Passo 1 — Crie um aplicativo OAuth do GitHub

Vá para https://github.com/settings/developers → Novo aplicativo OAuth
Preencha:
- Nome do aplicativo: AgentMemory (ou qualquer coisa que você goste)
- URL da página inicial: sua URL implantada (ex.: https://agentmemory-dusky.vercel.app) ou http://localhost:5173 para desenvolvimento local
- URL de callback de autorização: copie isso do Supabase no próximo passo — você voltará para editar
Clique em Registrar aplicativo
Na próxima página, clique em Gerar um novo segredo de cliente. Copie o ID do cliente e o Segredo do cliente (você não verá o segredo novamente)

Passo 2 — Conecte-o ao Supabase

De volta ao painel do Supabase → Autenticação → Provedores → GitHub
Ative Habilitar login com GitHub
Cole o ID do cliente e o Segredo do cliente do passo 1
Clique em Salvar
Em Autenticação → Configuração de URL, adicione suas URLs de site em URL do site e URLs de redirecionamento adicionais:
- http://localhost:5173 (dev)
- https://your-app.vercel.app (produção)
O Supabase agora mostra a URL de callback canônica para o seu projeto — ela se parece com https://<project-ref>.supabase.co/auth/v1/callback. Volte ao aplicativo OAuth do GitHub e cole isso em URL de callback de autorização

Passo 3 — Teste

Abra /auth no seu aplicativo → clique em Continuar com GitHub → você deve ser redirecionado ao GitHub, aprovar e voltar conectado. O avatar na barra lateral muda para a foto do seu perfil do GitHub e um botão Sair aparece no canto inferior esquerdo.

Pegadinha de self-hosting: todo domínio personalizado do qual você serve precisa ser adicionado às URLs de redirecionamento adicionais do Supabase, caso contrário o OAuth rejeitará o parâmetro redirectTo. O Supabase retorna um erro redirect_uri not in allowlist se você pular isso.

2. Configure o ambiente

Copie public/.env.example para .env (ou defina variáveis na Vercel):

VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGc...
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=eyJhbGc...
# Optional: enables pgvector semantic search via HuggingFace Inference API (free tier)
HUGGINGFACE_API_KEY=hf_xxxxxxxxxxxxxxxxxxxxxxxx
# Optional: per-user embedding rate limit (default 100/hr, protects HF free tier)
RATE_LIMIT_PER_HOUR=100
# Service role key NOT used — RLS scopes everything to auth.uid()

3. Implante na Vercel

npm i -g vercel
vercel
# accept defaults; add the SUPABASE_* env vars when prompted

O aplicativo web é um build estático de arquivo único (dist/index.html) na raiz. O servidor MCP é exposto como uma função serverless em /mcp e /api/mcp.

4. Use o MCP remoto

Clientes (Claude Desktop, Cursor, personalizados) podem se conectar ao seu servidor MCP hospedado via HTTP. Envie o JWT do Supabase do usuário no cabeçalho Authorization: Bearer <jwt>:

{
  "mcpServers": {
    "agentmemory-cloud": {
      "url": "https://your-app.vercel.app/mcp",
      "headers": {
        "Authorization": "Bearer <supabase-access-token>"
      }
    }
  }
}

A função valida o JWT via Supabase e depois consulta o Postgres com RLS para que cada usuário veja apenas seus próprios dados. Nenhuma chave de função de serviço é necessária para solicitações de usuário — o RLS faz o trabalho.

Arquitetura

src/
  store/memoryStore.ts        # Zustand store + pure logic helpers (hybridSearch, decay)
  utils/
    bm25.ts                   # BM25 inverted index
    rrf.ts                    # Reciprocal Rank Fusion
    stemmer.ts                # Compact Porter stemmer
    memoryDecay.ts            # calculateStrength, tierOf, touchMemory, runAutoForget
    jsonlImport.ts            # Claude Code session parser
  lib/supabase.ts             # Supabase browser client
  lib/cloudSync.ts            # Pull/push helpers used by memoryStore
  hooks/useAuth.ts            # Wires Supabase auth state to the store
  components/
    MemoryCard.tsx            # Tier badge + touch-on-mount
    Layout.tsx                # Sidebar with sign-in / cloud status
  pages/
    AuthPage.tsx              # Magic-link + GitHub OAuth sign-in
    ImportPage.tsx            # .jsonl + .md/.txt/.cursorrules dropzone
    SupportPage.tsx           # Donate CTA

mcp/
  server.ts                   # Transport-agnostic MCP server (9 tools + 3 resources)
  embeddings.ts               # HuggingFace Inference API wrapper (MiniLM-L6-v2, 384-dim)
  backends/
    local.ts                  # Reads/writes the zustand store on disk
    supabase.ts               # RRF search (BM25+vector+graph), embeds on add, RLS-scoped via caller's JWT
  index.ts                    # Stdio entrypoint (uses LocalBackend)

api/
  mcp.ts                      # Vercel serverless handler (Streamable HTTP)

supabase/
  schema.sql                  # Tables, RLS policies, search_memories / find_similar_memories RPCs

O modo local e o modo nuvem compartilham o mesmo tipo Memory e as mesmas ações memoryStore. A única diferença é se as mutações são espelhadas no Supabase.

Desenvolvimento

npm run dev                 # Vite dev server
npm run build               # Production web build
npm run mcp                 # Run stdio MCP server (tsx, no build step)
npm run typecheck:mcp       # tsc --noEmit on the MCP workspace
npx tsc --noEmit            # tsc --noEmit on the web workspace

Licença

MIT — veja LICENSE.