Início rápido para o XMemo

Use o XMemo como um lar de memória compartilhada para assistentes de IA: conecte um cliente, salve contexto útil uma vez, recupere-o depois e mantenha credenciais fora de configurações públicas.

Introdução #

Use o XMemo como um lar de memória compartilhada para assistentes de IA: conecte um cliente, salve contexto útil uma vez, recupere-o depois e mantenha credenciais fora de configurações públicas.

Um lar de memória

Mantenha preferências duradouras, fatos do projeto, decisões e notas de transição em uma camada de memória pertencente ao usuário que assistentes aprovados possam recuperar.

Conecte seu cliente

Use a URL hospedada do MCP com o perfil de cliente para ChatGPT, Claude, VS Code / GitHub Copilot, Copilot CLI, Codex, Gemini, Cursor ou executores MCP diretos.

Mantenha o controle

Use OAuth onde houver suporte, repasse de segredos via ambiente para clientes diretos e controles de conta para limites de revisão, exclusão e exportação.

Persona onboarding flows #

Usuário do ChatGPT

Goal: Dê ao ChatGPT acesso duradouro às suas preferências do XMemo, fatos do projeto, decisões e TODOs sem colar tokens bearer no chat.
Connection: Conecte o servidor MCP hospedado do XMemo pelo fluxo OAuth do app ChatGPT/OpenAI e aprove a concessão memory:read e memory:write para sua conta do XMemo.
Success action: Salve uma preferência de teste ou anotação de projeto, inicie um novo chat e peça ao ChatGPT para recuperá-la via XMemo antes de prosseguir.
Troubleshooting: Se o OAuth falhar ou as ferramentas não aparecerem, saia do servidor MCP no app host, reconecte a URL do servidor XMemo e tente novamente antes de criar tokens diretos.

Desenvolvedor Copilot / Codex

Goal: Transfira decisões do repositório, convenções de código, notas de correção de bugs e histórico de tarefas entre agentes de IDE e CLI.
Connection: Use OAuth para VS Code / GitHub Copilot e Gemini CLI quando disponível. Para Copilot CLI, Codex, Cursor ou outros clientes MCP diretos, mantenha XMEMO_KEY no ambiente local ou cofre de segredos e defina um XMEMO_AGENT_INSTANCE_ID estável.
Success action: Registre uma decisão da base de código ou correção de bug e peça ao próximo agente de IDE ou CLI para recuperar o contexto relevante do XMemo antes de editar.
Troubleshooting: Se as recuperações estiverem vazias, verifique o caminho da configuração MCP selecionada, a variável de ambiente XMEMO_KEY para clientes diretos e eventuais credenciais OAuth desatualizadas no app host.

Líder de piloto de equipe / corporativo

Goal: Avalie a memória compartilhada com controles de conta, atribuição de origem, fluxos de exportação/exclusão e evidências de configuração seguras para revisores.
Connection: Crie ou acesse o espaço de trabalho protegido do XMemo, convide usuários aprovados e conecte cada cliente via OAuth ou credencial direta com escopo de acordo com os selos de disponibilidade.
Success action: Peça para um membro do piloto salvar uma memória de equipe de teste, confirme a atribuição de origem no XMemo e revise os caminhos de exclusão/exportação e suporte.
Troubleshooting: Se um membro não conseguir se conectar, verifique as permissões de função, aprovação OAuth, status de prontidão do cliente e orientações de suporte antes de emitir um novo token.

Operador de agentes autônomos

Goal: Permita que agentes headless ou agendados registrem progresso, recuperem decisões anteriores e mantenham uma identidade estável e não secreta de instância.
Connection: Obtenha /api/v1/mcp/config/autonomous-agent. Prefira auth_modes.oauth quando o executor suportar OAuth + cabeçalhos personalizados; use auth_modes.xmemo_key com XMEMO_KEY de um cofre de segredos apenas para executores totalmente headless.
Success action: Execute uma tarefa de teste que grave progresso no XMemo, reinicie o executor e confirme se ele recupera esse progresso usando o mesmo XMEMO_AGENT_INSTANCE_ID.
Troubleshooting: Se a atribuição mudar ou as recuperações se dividirem entre instâncias, persista XMEMO_AGENT_INSTANCE_ID fora do git e verifique se o executor não o está gerando a cada início.

Controles do Console de Memória #

O XMemo não é apenas um endpoint MCP. O Console de Memória é o espaço voltado ao usuário para revisar, corrigir, remover e exportar memórias, mantendo a atribuição do agente visível.

Visualizar e pesquisar memórias

Abra o console para ver memórias salvas, inspecionar caminhos e tipos de memória, e confirmar se uma recuperação deveria ter retornado um item específico.

Editar ou corrigir entradas

Corrija fatos desatualizados, mova itens para caminhos mais claros ou substitua anotações antigas para que assistentes futuros recuperem o contexto mais recente aprovado pelo usuário.

Excluir e exportar

Use os fluxos da conta para remover memórias que não deseja mais e localizar caminhos de exportação para revisão de memórias no escopo da conta.

Atribuição de agente

Revise qual cliente ou executor gravou uma memória, incluindo rótulos não secretos de agente e instância quando o cliente os envia.

Controles de privacidade e credenciais

Mantenha o consentimento OAuth, o uso de tokens diretos, o repasse de segredos via ambiente e os limites de suporte visíveis antes de expandir um piloto pessoal ou em equipe.

Solicitar acesso ao XMemo #

Abrir entrada da conta ↗

Início rápido do XMemo hospedado #

Comece com o serviço gerenciado do XMemo e uma destas opções de conexão. Configurações auto-hospedadas, Docker, Supabase e pacotes Python são referências para desenvolvedores, não a rota inicial para usuários hospedados.

Pergunte ao seu agente

Cole isto em um agente confiável para seguir suas verificações normais de segurança.

Instale a Skill autônoma do XMemo no seu diretório de skills: execute o instalador de https://xmemo.dev/skill/install (no Windows, https://xmemo.dev/skill/install.ps1) com XMEMO_SKILL_DIR definido para o seu diretório de skills mais /xmemo-memory. Execute o comando doctor exibido para verificar a instalação, depois recarregue suas skills e siga as etapas de primeira execução da Skill. Siga suas verificações de segurança normais e não use privilégios elevados.

Clientes OAuth

Use este caminho para ChatGPT, revisão de app da OpenAI, VS Code e GitHub Copilot quando o host suportar OAuth. Adicione a URL hospedada do MCP, aprove memory:read e memory:write, e não cole XMEMO_KEY na configuração do cliente.

MCP URL: https://xmemo.dev/mcp
Scopes: memory:read memory:write

MCP direto com XMEMO_KEY

Use este caminho apenas para clientes ou executores headless que não consigam concluir OAuth. Armazene XMEMO_KEY no ambiente local ou cofre de segredos, mantenha a URL hospedada do MCP na configuração e nunca cole o token real em documentos públicos ou chat.

MCP URL: https://xmemo.dev/mcp
Token source: XMEMO_KEY environment variable
Optional identity: XMEMO_AGENT_INSTANCE_ID

Controles de conta

Após a primeira conexão, use o acesso à conta para revisar o que foi salvo, conferir a atribuição de agentes e localizar caminhos de exclusão/exportação ou suporte antes de expandir um piloto.

Account entry: https://xmemo.dev/login

Segurança pública #

A descoberta pública é somente leitura e não contém segredos.
Client setup requires secrets in environment variables or a system secret store, not in generated URLs.
Os documentos públicos do produto evitam intencionalmente links para consoles de operador, documentação de API, JSON de descoberta, catálogos de instaladores, URLs brutas de bootstrap, URLs brutas de serviço e material de credenciais.

Evidência de origem #

Documentação baseada no código-fonte da rota de descoberta do XMemo, do contrato de descoberta hospedada, do servidor MCP e do SDK TypeScript.

Perguntas frequentes / Solução de problemas #

Por que meu assistente de IA não se lembra de algo que eu contei antes? —
Por que meu assistente de IA está misturando meus projetos ou conversas? —
Como faço para que meu assistente de IA esqueça algo completamente? —
Troquei de computador ou de assistente de IA; o XMemo ainda vai se lembrar de mim? —
Por que meu assistente de IA salvou a mesma coisa duas vezes? —
Por que meu assistente de IA está trazendo contexto demais ou de menos do meu histórico? —
Desconectei o XMemo; como garanto que o assistente antigo não possa mais usá-lo? —
Por que meu assistente de IA não consegue mais usar o XMemo? —
Qual conexão do XMemo devo usar no meu assistente de IA? —
O que faço se meu assistente de IA ainda não conseguir se conectar ao XMemo? —

Pré-requisitos #

Approved service URL - Used by xmemo setup --url to fetch discovery, onboarding status, and MCP config templates.
Node.js and npm - Discovery and the product page advertise @xmemo/client as the public CLI package.
Scoped token or OAuth grant - ChatGPT and VS Code / GitHub Copilot use OAuth; direct MCP and REST clients use XMEMO_KEY from an environment variable or secret store.

Conectar com o XMemo #

xmemo setup --url drives the entire trial. The documented hosted setup flow is implemented as discovery → onboarding status → MCP config template → reviewed client configuration.

npm install -g @xmemo/client
npx @xmemo/client setup --url https://xmemo.dev

Configuração de MCP #

XMemo MCP setup lives in Docs because auth differs by client. ChatGPT, VS Code / GitHub Copilot, and Gemini CLI use hosted OAuth; direct/headless clients use the hosted Streamable HTTP URL plus XMEMO_KEY from the local environment or secret store.

VS Code / GitHub Copilot

%APPDATA%\Code\User\mcp.json

{
  "servers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp"
    }
  }
}

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "cursor",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Codex

~/.codex/config.toml

[mcp_servers.XMemo]
url = "https://xmemo.dev/mcp"
bearer_token_env_var = "XMEMO_KEY"

[mcp_servers.XMemo.http_headers]
X-Memory-OS-Agent-ID = "codex"

[mcp_servers.XMemo.env_http_headers]
X-Memory-OS-Agent-Instance-ID = "XMEMO_AGENT_INSTANCE_ID"

Gemini CLI

~/.gemini/settings.json

{
  "mcpServers": {
    "XMemo": {
      "httpUrl": "https://xmemo.dev/mcp",
      "headers": {
        "X-Memory-OS-Agent-ID": "gemini-cli",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "XMemo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://xmemo.dev/mcp",
        "--header",
        "Authorization:Bearer ${XMEMO_KEY}",
        "--header",
        "X-Memory-OS-Agent-ID:claude-desktop",
        "--header",
        "X-Memory-OS-Agent-Instance-ID:${XMEMO_AGENT_INSTANCE_ID}"
      ],
      "env": {
        "XMEMO_AGENT_INSTANCE_ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Devin Desktop (formerly Windsurf)

~/.config/devin/mcp_config.json

{
  "mcpServers": {
    "XMemo": {
      "serverUrl": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "windsurf",
        "X-Memory-OS-Agent-Instance-ID": "${env:XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Kiro

~/.kiro/settings/mcp.json

{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "X-Memory-OS-Agent-ID": "kiro",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      },
      "oauth": {
        "oauthScopes": [
          "memory:read",
          "knowledge:read"
        ]
      }
    }
  }
}

Muse Code

~/.config/muse/settings.json

{"schema_version": 1, "mcpServers": {"xmemo": {"type": "streamable-http", "url": "https://xmemo.dev/mcp", "mode": "optional"}}}

OpenClaw

~/.openclaw/openclaw.json

{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "openclaw",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Copilot CLI

~/.copilot/mcp-config.json

{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

ChatGPT / OpenAI Apps SDK

Painel de gerenciamento de aplicativos da OpenAI Platform

{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "transport": "streamable-http",
      "auth": {
        "type": "oauth2",
        "resource": "https://xmemo.dev/mcp",
        "scopes": ["memory:read", "memory:write"]
      }
    }
  }
}

Autonomous agent

Configuração MCP do executor de agentes

{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "transport": "streamable-http",
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "X-Memory-OS-Agent-ID": "autonomous-agent",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      },
      "auth": {
        "type": "oauth2",
        "flow": "authorization_code",
        "pkce_required": true,
        "resource": "https://xmemo.dev/mcp",
        "scopes": ["memory:read", "memory:write"]
      },
      "fallback": {
        "use_when": "headless runner cannot complete OAuth sign-in or persist OAuth tokens",
        "authorization_header": "Bearer ${XMEMO_KEY}"
      }
    }
  }
}

Outro

Qualquer agente compatível com MCP

{
  "mcpServers": {
    "XMemo": {
      "transport": "streamable-http",
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "${XMEMO_AGENT_ID}",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Kimi Code

~/.kimi-code/mcp.json

{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "bearerTokenEnvVar": "XMEMO_KEY",
      "headers": {
        "X-Memory-OS-Agent-ID": "kimi-code",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Claude Code

~/.claude.json

{
  "mcpServers": {
    "XMemo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://xmemo.dev/mcp",
        "--header",
        "Authorization:Bearer ${XMEMO_KEY}",
        "--header",
        "X-Memory-OS-Agent-ID:claude-code",
        "--header",
        "X-Memory-OS-Agent-Instance-ID:${XMEMO_AGENT_INSTANCE_ID}"
      ],
      "env": {
        "XMEMO_AGENT_INSTANCE_ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "XMemo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://xmemo.dev/mcp",
        "--header",
        "Authorization:Bearer ${XMEMO_KEY}",
        "--header",
        "X-Memory-OS-Agent-ID:claude-desktop",
        "--header",
        "X-Memory-OS-Agent-Instance-ID:${XMEMO_AGENT_INSTANCE_ID}"
      ],
      "env": {
        "XMEMO_AGENT_INSTANCE_ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Cline (VS Code)

~/Documents/Cline/MCP/cline_mcp_settings.json

{
  "mcpServers": {
    "XMemo": {
      "httpUrl": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "cline",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Continue (VS Code / JetBrains)

~/.continue/config.json

{
  "mcpServers": {
    "XMemo": {
      "transport": {
        "type": "streamable-http",
        "url": "https://xmemo.dev/mcp",
        "headers": {
          "Authorization": "Bearer ${XMEMO_KEY}",
          "X-Memory-OS-Agent-ID": "continue",
          "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
        }
      }
    }
  }
}

Zed

Zed settings.json (varies by OS)

{
  "context_servers": {
    "XMemo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://xmemo.dev/mcp",
        "--header",
        "Authorization:Bearer ${XMEMO_KEY}",
        "--header",
        "X-Memory-OS-Agent-ID:zed",
        "--header",
        "X-Memory-OS-Agent-Instance-ID:${XMEMO_AGENT_INSTANCE_ID}"
      ],
      "env": {
        "XMEMO_AGENT_INSTANCE_ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Trae

Trae user config mcp.json (varies by OS)

{
  "mcpServers": {
    "XMemo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://xmemo.dev/mcp",
        "--header",
        "Authorization:Bearer ${XMEMO_KEY}",
        "--header",
        "X-Memory-OS-Agent-ID:trae",
        "--header",
        "X-Memory-OS-Agent-Instance-ID:${XMEMO_AGENT_INSTANCE_ID}"
      ],
      "env": {
        "XMEMO_AGENT_INSTANCE_ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Grok

~/.grok/config.toml

{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "grok",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Antigravity 2.0

~/.gemini/config/mcp_config.json

{
  "mcpServers": {
    "XMemo": {
      "serverUrl": "https://xmemo.dev/mcp",
      "headers": {
        "X-Memory-OS-Agent-ID": "antigravity",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Qwen

~/.qwen/settings.json

{
  "mcpServers": {
    "XMemo": {
      "httpUrl": "https://xmemo.dev/mcp",
      "headers": {
        "X-Memory-OS-Agent-ID": "qwen",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

OpenCode

~/.config/opencode/opencode.json

{
  "mcp": {
    "XMemo": {
      "type": "remote",
      "url": "https://xmemo.dev/mcp",
      "enabled": true,
      "headers": {
        "X-Memory-OS-Agent-ID": "opencode",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Client capability matrix #

The canonical matrix is the source of truth for each client's OAuth mode, MCP transport, credential handling, readiness, evidence boundary, and marketplace state. This page only provides the setup console; do not copy a status into another page without checking the matrix.

Read CLIENT_CAPABILITY_MATRIX.md on GitHub ↗

Preset de agente autônomo #

Autonomous agents should fetch /api/v1/mcp/config/autonomous-agent instead of asking humans to choose identity fields.

Superfície de ferramentas MCP #

The discovery response lists the actual MCP transport as streamable-http and advertises tools implemented by the XMemo MCP server.

Recall tools - search_memory, recall, recall_plan, and recall_context.
Write tools - remember, store_memory, update_memory, and record_event.
Governance tools - forget_memory, redact_memory, explain_memory, and conflict/version helpers.

Auxiliares de fluxo de trabalho do SDK #

The TypeScript SDK exposes workflow helpers in packages/memory-os-js. These helpers route events through capture policy before writing memory.

Habilidades e agentes #

Skills are the instruction-and-command lane for agents that do not mount a hosted MCP server directly.

Início rápido para o XMemo

Introdução #

Persona onboarding flows #

Usuário do ChatGPT

Desenvolvedor Copilot / Codex

Líder de piloto de equipe / corporativo

Operador de agentes autônomos

Controles do Console de Memória #

Visualizar e pesquisar memórias

Editar ou corrigir entradas

Excluir e exportar

Atribuição de agente

Controles de privacidade e credenciais

Solicitar acesso ao XMemo #

Início rápido do XMemo hospedado #

Pergunte ao seu agente

Clientes OAuth

MCP direto com XMEMO_KEY

Controles de conta

Segurança pública #

Evidência de origem #

Perguntas frequentes / Solução de problemas #

Pré-requisitos #

Conectar com o XMemo #

Configuração de MCP #

VS Code / GitHub Copilot

Cursor

Codex

Gemini CLI

Claude Desktop

Devin Desktop (formerly Windsurf)

Kiro

Muse Code

OpenClaw

Copilot CLI

ChatGPT / OpenAI Apps SDK

Autonomous agent

Outro

Kimi Code

Claude Code

Claude Desktop

Cline (VS Code)

Continue (VS Code / JetBrains)

Zed

Trae

Grok

Antigravity 2.0

Qwen

OpenCode

Client capability matrix #

Preset de agente autônomo #

Superfície de ferramentas MCP #

Auxiliares de fluxo de trabalho do SDK #

Habilidades e agentes #

Próximas etapas #