MarsNMe

Backend de memória persistente agnóstico a agentes. 13 ferramentas MCP, Supabase + embeddings Jina, isolamento multi-perfil, recordação semântica entre sessões.

GitHub

Experimente este MCPPatrocinado

Documentação

English | 繁體中文（台灣） | 繁體中文（香港） | 简体中文

marsnme.com — Claude.md é para contexto. MarsNMe é para continuidade.

Suas ferramentas de IA deveriam conhecer você — não começar do zero toda vez. Quando o Perplexity ajuda você a decidir, o Claude deveria lembrar o porquê. Quando o Cursor entrega um recurso, o Warp deveria saber o contexto. Isso não é compartilhamento de contexto. Isso é continuidade.

A maioria das ferramentas de memória de IA ajuda a IA a lembrar de você. O MarsNMe ajuda você e sua IA a lembrarem um do outro — entre sessões, entre ferramentas, ao longo do tempo.

Um backend de memória agnóstico de agente e agnóstico de LLM para ferramentas compatíveis com MCP.

curl -fsSL https://marsnme.com/install.sh | bash

MarsNMe dark mode demo

MarsNMe light mode demo

História real de usuário

Eu uso Cursor para codar, Warp para deploy, Perplexity para pesquisar e Claude Code para gerenciar meu vault. Antes do MarsNMe, toda ferramenta começava em branco — eu tinha que reexplicar meu projeto, minhas preferências, minhas decisões em toda sessão. Agora minha IA em todas as quatro ferramentas sabe o que decidimos ontem, o que tentamos na semana passada e por que escolhemos esta arquitetura em vez daquela. Não se trata de injetar contexto. Trata-se de ter um relacionamento que se acumula ao longo do tempo.

— Leo, criador do MarsNMe (3 meses de uso diário em 4 ferramentas de IA)

Ferramentas MCP disponíveis (16)

Ferramenta	Descrição
`insert_memory`	Armazenar memória de curto prazo
`list_memories`	Listar memórias recentes
`search_memories`	Busca semântica via embeddings Jina
`recall`	Recuperação de chunks de longo prazo — ~80 caracteres de pré-visualização por correspondência
`get_summary`	Trecho médio (~300 caracteres) de um chunk por ID
`get_full`	Texto completo de um chunk de longo prazo por ID
`memory_ingest`	Ingerir chunks de insights de longo prazo
`dream_ingest`	Ingestão de longo prazo em modo sonho
`session_boot`	Iniciar uma sessão com pré-carregamento de contexto
`session_close`	Fechar sessão, resumir, promover automaticamente memórias expirando
`health_check`	Diagnósticos de cobertura, expiração e conflitos
`reload_source_registry`	Atualizar whitelist de fontes em tempo de execução
`demote_memory`	Rebaixar uma memória para prioridade menor
`soft_forget`	Exclusão suave de uma memória
`explain_memory`	Explicar a proveniência de uma memória
`batch_promote`	Promover memórias de curto prazo expirando para longo prazo

O que há de novo na 0.3.0

Recuperação em 3 camadas: recall retorna pré-visualizações de ~80 caracteres, depois get_summary (~300 caracteres), depois get_full (completo). Evita despejar chunks completos em toda recuperação; aprofunde-se apenas quando uma pré-visualização parecer relevante.
Transferência de notas corpo a corpo: session_close(to=<body>, note=...) deixa uma nota que session_boot(body=<target>) entrega e marca como lida — um agente pode passar contexto para outro.
batch_promote automático no session_close: fechar uma sessão promove automaticamente memórias de curto prazo que expiram em breve (janela de 48h, até 5) para armazenamento de longo prazo — sem necessidade de Hermes ou promoção manual.
Fontes grok + draft: adicionadas à whitelist de fontes para que o corpo Grok e os hooks de ciclo de vida do Draft possam escrever memórias nativamente.
Superfície de ferramentas somente CoCo: ferramentas de PRD (save_prd, get_prd, list_prds, score_prd, spawn_to_linear) removidas do gateway Supabase — execução de ideia/PRD/tarefa agora vive no Draft. MarsNMe = memória da alma CoCo apenas.

MarsNMe

Por que MarsNMe?

A maioria das ferramentas de memória de IA ajuda a IA a lembrar de você. O MarsNMe ajuda você e sua IA a lembrarem um do outro.

	MarsNMe	Ferramenta de memória típica
Filosofia	Continuidade mútua — humano + IA crescem juntos	Injeção de contexto apenas no lado da IA
Suporte a agentes	Qualquer cliente compatível com MCP	Frequentemente específico do cliente
Camadas de memória	Curto prazo (TTL) + longo prazo (semântico)	Geralmente uma camada
Perfis	Perfis isolados ilimitados via `MCP_PROFILE`	Apenas usuário único
Propriedade dos dados	Seu próprio Supabase — zero dependência de fornecedor	Hospedado pelo fornecedor
Busca	Busca semântica Jina v3 (pgvector 1024-dim)	Palavra-chave ou similaridade básica
Auto-hospedável	✅ Controle total	Raramente

Quando MarsNMe é a escolha certa

Você usa vários assistentes de IA (Claude, Cursor, Perplexity, Warp, agentes personalizados) e quer memória compartilhada entre todos eles
Você quer IA que lembre seus projetos, preferências e decisões entre sessões sem reexplicar
Você se importa com soberania de dados — suas memórias ficam no seu próprio projeto Supabase
Você está construindo um agente de IA e precisa de um backend de memória pronto para produção com recuperação semântica

Quando pode não ser a escolha certa

Você só precisa de contexto de sessão única (apenas use o system prompt)
Você quer memória totalmente gerenciada, sem configuração (tente uma solução hospedada)

Pacotes de runtime

Pasta	Runtime	Quem usa
`marsnme-supabase/`	Gateway Supabase + Jina (`@marsnme/mcp-gateway`)	Dogfood do Mars Group — Proxmox CT101 (memória da alma CoCo / Toto)
`marsnme-cf/`	Cloudflare Workers + D1 + Vectorize	Template de auto-hospedagem; não é o caminho de deploy Proxmox
`marsnme-supabase/cloudflare-routing-worker/`	Proxy de roteamento `mcp.marsnme.com`	Assistente de configuração público → gateway upstream

Divisão de produto (Mars Group): Execução de ideia / PRD / tarefa → Draft + draft-mcp. MarsNMe Supabase = memória da alma CoCo apenas (recuperação, início/fim de sessão, ingestão, ciclo de vida). A partir de @marsnme/mcp-gateway v0.3.0, as ferramentas MCP de PRD (save_prd, get_prd, list_prds, score_prd, spawn_to_linear) são removidas do gateway Supabase — use Draft para fluxos de trabalho de ideia/PRD/tarefa.

Deploy Proxmox: MarsNMe-lab privado — deploy/deploy-proxmox-ct101.sh ou fluxo de trabalho GitHub cd-selfhosted. Não é um deploy de script único como draft-mcp.

Pacotes do repositório

Pacote	Descrição
`marsnme-supabase/`	Gateway MCP principal — backend de memória agnóstico de agente (este pacote é publicado no npm como `@marsnme/mcp-gateway`)
`marsnme-supabase/cloudflare-routing-worker/`	Cloudflare Worker para `mcp.marsnme.com` — proxy de roteamento MCP baseado em nome de usuário com assistente de configuração
`marsnme-cf/`	Servidor de memória MCP auto-hospedado em Cloudflare Workers + D1 + Vectorize (sem necessidade de Supabase)

Configuração rápida (sem instalação)

Vá para mcp.marsnme.com/setup — crie sua URL MCP pessoal em 4 passos:

Escolha um nome de usuário
Insira suas credenciais do Supabase (URL + chave anônima)
Escolha preferências
Obtenha sua URL MCP: https://mcp.marsnme.com/your-name

Depois adicione a qualquer cliente MCP (Claude, Cursor, Perplexity, Warp).

Auto-hospedado? Faça deploy do marsnme-cf/ na sua própria conta Cloudflare — sem necessidade de Supabase, usa D1 + Workers AI + Vectorize.

Antes de começar (dependências externas)

Crie um projeto Supabase (o plano gratuito é suficiente):
- Cadastre-se: https://supabase.com
- Crie o projeto: https://supabase.com/dashboard/new
- Abra as configurações de API (Project Settings → API):
  - URL do projeto → SUPABASE_BASE_URL
  - Chave service_role → SUPABASE_SERVICE_ROLE_KEY
- Mantenha SUPABASE_SERVICE_ROLE_KEY privada. Nunca a envie para o repositório.
Crie uma chave de API Jina (camada gratuita disponível):
- Obtenha a chave: https://jina.ai/api-key/
- Copie a chave para JINA_API_KEY

Início rápido (15-20 minutos)

Para o caminho mais rápido, use o instalador de uma linha: curl -fsSL https://marsnme.com/install.sh | bash

O caminho manual abaixo segue o mesmo fluxo de ferramentas primeiro que docs/onboarding-a-mcp-zero-to-recall.md e docs/onboarding-b-platform-skill-install.md.

Clone o repositório:

git clone https://github.com/Marsmanleo/MarsNMe.git
cd MarsNMe

Verifique a versão do Node.js (20+ necessário):

node --version

Copie o modelo de ambiente:

cp .env.example .env

Preencha os valores necessários em .env:
- SUPABASE_BASE_URL
- SUPABASE_SERVICE_ROLE_KEY
- JINA_API_KEY
Execute as migrações Supabase necessárias antes do primeiro início:
- Opção A (recomendada, CLI Supabase):

npx supabase db push --db-url "<your-supabase-db-connection-string>"

Nota: --db-url deve ser a string de conexão do banco de dados Postgres de Project Settings → Database → Connection string.
Não é o mesmo que SUPABASE_BASE_URL (https://<project-ref>.supabase.co, URL da API REST).
Use um papel que possa executar DDL nos seus schemas de destino.
No Postgres hospedado pelo Supabase, isso é tipicamente supabase_admin (não postgres).
Opção B (Editor SQL do painel Supabase):
1. Abra o Editor SQL.
2. Certifique-se de que a extensão vector esteja habilitada primeiro (Database → Extensions).
3. Execute os arquivos de migração em ordem de nome de supabase/migrations/:
  - 20260504052744_semantic_vector_dual_profile.sql
  - 20260513213800_memory_lifecycle_tracking.sql
  - 20260513222500_health_check_detect_conflicts_v2.sql
  - 20260517183000_provenance_audit_trail.sql
  - 20260517194000_memory_scope_agent_body_environment.sql
  - 20260517200500_forget_demote_mechanism.sql
  - 20260517223500_usage_cost_telemetry_light.sql
  - 20260517231000_memories_source_constraint_regex.sql
  - 20260517232000_source_registry_table.sql

Inicie o gateway:
- MCP_PROFILE separa memória por agente ou caso de uso.
- Use qualquer nome de perfil que quiser (por exemplo: default, my-agent, profile-a).
- IDs de perfil legados integrados coco e toto ainda são suportados para compatibilidade.
- Se PORT for omitido, a porta padrão é baseada no perfil (coco=18790, toto=18791, outros perfis determinísticos em 20000-29999).

MCP_PROFILE=profile-a PORT=18790 npx @marsnme/mcp-gateway

Verifique a saúde:

curl -sS http://127.0.0.1:18790/health

Conecte seu cliente MCP (próxima seção) e execute a primeira verificação de ida e volta.

Experimente em 30 segundos (Docker, M1)

Se você só quer um caminho de demonstração local, use Docker Compose.

Instalação de uma linha (recomendada):

curl -fsSL https://marsnme.com/install.sh | bash

Ou manualmente:

Defina apenas a chave necessária:

cp .env.example .env
# fill JINA_API_KEY in .env

Inicie a stack local:

docker compose up

Isso inicia:

PostgreSQL + pgvector
Migrações SQL de supabase/migrations/
PostgREST + rest-proxy
Gateway MarsNMe (http://127.0.0.1:18790/mcp)

Verifique a saúde:

curl -sS http://127.0.0.1:18790/health

Perfil de túnel Cloudflare M2 (demonstração)

Quando você precisa de um endpoint público temporário para ferramentas de IA remotas:

docker compose --profile tunnel up

Saída esperada (dos logs de tunnel):

https://xxxx.trycloudflare.com

Obtenha o endpoint MCP:

docker compose --profile tunnel logs tunnel | grep -Eo 'https://[^ ]+trycloudflare.com' | head -n1
# append /mcp

Notas:

A URL trycloudflare.com é temporária (apenas demonstração).
O endpoint local permanece: http://127.0.0.1:18790/mcp.
Para URL de produção/estável, use túnel nomeado (fora do escopo M2).
Env opcional:
- MCP_TUNNEL_PROFILE (padrão coco)
- MCP_TUNNEL_REQUIRE_BEARER (padrão false para conveniência de demonstração)

Guia de conexão do cliente MCP

Endpoint local:

http://127.0.0.1:18790/mcp

Se a autenticação bearer estiver habilitada (MCP_REQUIRE_BEARER=true), inclua:

Authorization: Bearer <your-token>

Claude Desktop

Abra claude_desktop_config.json (caminho padrão macOS: ~/Library/Application Support/Claude/claude_desktop_config.json).
Adicione/atualize:

{
  "mcpServers": {
    "marsnme-cf": {
      "url": "http://127.0.0.1:18790/mcp"
    }
  }
}

Reinicie o Claude Desktop.

Cursor

Abra as Configurações do Cursor e procure por MCP.
Adicione um novo servidor:
- Nome: marsnme-cf
- URL: http://127.0.0.1:18790/mcp
- Headers: header bearer opcional se habilitado
Reconecte o MCP no Cursor.

Warp

Abra Settings > Agents > MCP servers.
Adicione um servidor apontando para:
- URL: http://127.0.0.1:18790/mcp
Adicione header bearer opcional se necessário e reconecte.

Perplexity

Abra um Space no Perplexity e vá para as Configurações do Space.
Em servidores MCP, adicione:
- URL: http://127.0.0.1:18790/mcp
Salve e inicie uma nova conversa nesse Space.

Qualquer cliente MCP (HTTP/SSE genérico)

Use uma entrada MCP HTTP/SSE transmissível:

{
  "marsnme-cf": {
    "url": "http://127.0.0.1:18790/mcp"
  }
}

Validação da primeira conexão (ida e volta)

Após a conexão do cliente, verifique esta sequência uma vez:

tools/list:

curl -sS http://127.0.0.1:18790/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

insert_memory:

curl -sS http://127.0.0.1:18790/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"insert_memory","arguments":{"body":"quickstart memory check","source":"warp","session_id":"quickstart-smoke"}}}'

recall:

curl -sS http://127.0.0.1:18790/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"recall","arguments":{"query":"quickstart memory check","limit":3}}}'

O que é este repositório

mars-memory-mcp é o repositório do gateway MCP principal por trás da versão pública do MarsNMe.
Um código-base (marsnme-supabase/server.mjs) atende a múltiplos schemas de perfil através de MCP_PROFILE. Este repositório público atualmente mantém dois IDs de perfil legados integrados (coco, toto) para compatibilidade retroativa.

Capacidades atuais

Métodos MCP: initialize, notifications/initialized, tools/list, tools/call, ping
Perfis: IDs de perfil configuráveis (built-ins legados: coco, toto)
Ferramentas de memória (16):
- insert_memory (memória de curto prazo)
- list_memories
- search_memories (busca por embeddings Jina)
- recall (pré-visualização de ~80 caracteres) depois get_summary (trecho de ~300 caracteres) depois get_full (texto completo)
- memory_ingest / dream_ingest (ingestão de fragmentos de longo prazo)
- session_boot / session_close (ciclo de vida do ritmo diário; o fechamento promove automaticamente memórias expirantes + suporta transferência de notas corpo a corpo)
- health_check (diagnósticos de cobertura, expiração e conflitos)
- reload_source_registry (atualizar a lista de fontes permitidas em tempo de execução)
- demote_memory / soft_forget / explain_memory (gerenciamento do ciclo de vida da memória)
- batch_promote (promover memórias de curto prazo expirantes para longo prazo)
Fontes: perplexity, cursor, warp, openclaw, hermes, draft, grok
Endpoint MCP protegido por OAuth (configurável por variáveis de ambiente)

Modelo de memória

Tabela de memória de curto prazo: <profile>.memories
Tabela de memória de longo prazo: <profile>.marsvault_chunks
Uso recomendado:
- Mantenha o contexto de interação diária em insert_memory
- Promova insights duradouros por meio das ferramentas de ingestão

Estrutura do repositório

marsnme-supabase/server.mjs — ponto de entrada do gateway
marsnme-supabase/scripts/hermes_digest_runner.py — executor de digest opcional
marsnme-supabase/scripts/dream_runner.py — executor público de dream runner auto-hospedado
marsnme-supabase/deploy/systemd/ — modelos systemd
marsnme-supabase/deploy/phase2/ — scripts de build/deploy
marsnme-supabase/deploy/phase3/smoke_gate.sh — script de verificação de smoke test
supabase/migrations/ — migrações de schema como código

Configuração do ambiente

Copie .env.example para o seu .env local (não faça commit de segredos reais).
Preencha os valores obrigatórios:
- MCP_PROFILE (seu identificador de perfil; este repositório acompanha os legados coco/toto)
- SUPABASE_BASE_URL
- SUPABASE_SERVICE_ROLE_KEY
- JINA_API_KEY
Flags de segurança opcionais:
- MCP_REQUIRE_BEARER=true
- MCP_CLIENT_ID
- MCP_CLIENT_SECRET

Executor de digest Hermes (opcional)

O Hermes é opcional e desabilitado por padrão:

HERMES_ENABLED=false
HERMES_DIGEST_MCP_URL
HERMES_DIGEST_MCP_BEARER_TOKEN
HERMES_DIGEST_ORIGIN
HERMES_DIGEST_SOURCE_DIR

Dream Runner (auto-hospedado, opcional)

O Dream Runner é voltado ao público e pode ser executado sem o ambiente privado do Hermes:

DREAM_ENABLED=true
DREAM_MODE=lite|standard|pro
DREAM_DIGEST_MCP_URL
DREAM_MCP_BEARER_TOKEN (se necessário)
DREAM_ENABLE_ISSUE_SIGNALS, DREAM_ENABLE_REPO_SCAN, DREAM_ENABLE_SOUL_CONTEXT (substituições opcionais)

Início rápido:

DREAM_ENABLED=true DREAM_MODE=lite python3 marsnme-supabase/scripts/dream_runner.py

Se você executar este repositório com os padrões incluídos e sem remapeamento de perfil, use coco e toto.

Consulte docs/dream-runner-self-host.md para a configuração completa.

Onboarding

Guia do zero à primeira recordação: docs/onboarding-a-mcp-zero-to-recall.md
Guia de instalação da plataforma (camada de habilidades opcional): docs/onboarding-b-platform-skill-install.md

Biblioteca de habilidades

Índice de habilidades e fluxo de atualização: skills/README.md
Modelo Perplexity: skills/perplexity/memory-daily-boot/SKILL.md
Modelo Cursor: skills/cursor/memory-daily-boot/rule.mdc
Modelo Warp: skills/warp/memory-daily-boot/prompt.md

Execução local (a partir do repositório clonado)

MCP_PROFILE=profile-a npx @marsnme/mcp-gateway

MCP_PROFILE=profile-b npx @marsnme/mcp-gateway

Endpoints de saúde:

GET /health
POST /mcp

Implantação com systemd

Use marsnme-supabase/deploy/systemd/memory-mcp-gateway@.service com instâncias:

memory-mcp-gateway@profile-a.service
memory-mcp-gateway@profile-b.service

Arquivos de ambiente recomendados:

/opt/mars-memory-mcp/shared/.env
/opt/mars-memory-mcp/shared/.env.profile-a
/opt/mars-memory-mcp/shared/.env.profile-b

Scripts de release/deploy

Compile o artefato:

bash marsnme-supabase/deploy/phase2/build_release_artifact.sh

Aplique as migrações com um papel explícito com capacidade DDL:

npx supabase db push --db-url "<postgres://supabase_admin:<password>@<host>:5432/postgres>"

Execute a verificação de schema pré-deploy (deve passar antes de qualquer reinício de serviço):

bash marsnme-supabase/deploy/phase2/pre_deploy_schema_gate.sh \
  --db-url "<postgres://supabase_admin:<password>@<host>:5432/postgres>" \
  --profiles coco,toto \
  --expected-role supabase_admin

Execute o adaptador de rollout/reinício específico da sua plataforma.
- Este repositório inclui scripts genéricos de artefato e verificação; os adaptadores de rollout são específicos do ambiente.
- Se a verificação de schema sair com código diferente de zero, interrompa a implantação e não reinicie os serviços.
Verificação de smoke test:

bash marsnme-supabase/deploy/phase3/smoke_gate.sh --spawn-local

Release automatizado para npm + MCP Registry (orientado por tags):
- Workflow: .github/workflows/publish-release.yml
- Gatilho: push da tag v*
- Verificação: a versão da tag deve corresponder à versão de marsnme-supabase/package.json
- Helper local opcional para Fish:

mrel patch
mrel minor
mrel major
mrel 0.1.2

O helper atualiza marsnme-supabase/package.json e server.json, faz commit, cria a tag e faz push.

Segurança e controle de versão

Nunca faça commit de .env, tokens de runtime ou oauth-clients.json
Mantenha .env.example versionado como o único modelo de ambiente
Prefira bearer/OAuth para exposição pública

Licença e políticas

Licença: Apache-2.0 (LICENSE)
Aviso: NOTICE
Política de marcas registradas: TRADEMARK.md
Guia de contribuição: CONTRIBUTING.md
Acordo de contribuição: CLA.md
Notas de versão: CHANGELOG.md