# Guia de projetos

Crie espaços de trabalho de projetos pessoais, gerencie associações de memória, acompanhe TODOs e decisões, e delimite o contexto de agentes.

- Canonical: https://docs.xmemo.dev/pt-br/docs/guides/projects
- Locale: pt-BR
- Content-Locale: pt-BR
- Canonical-Content-Digest: 7f95ace70e5137cfc69dccdd21827d3a6a830c65f25f2cff83b344d35824c8ef
- Edition-Digest: 7c9ed3e89bb0380c7ff1db99be1fb07517bb96cbe9957331bb9893b5889a186f
- Source-Revision: sha256:192851794c728ed3868a5be3be886563c1566aa6aec82e2a9d21109e443f6368

## Objetivo do usuário

Estabeleça um espaço de trabalho de projeto dedicado para organizar memórias contextuais, acompanhar decisões operacionais e tarefas ativas, recuperar contexto focado do projeto em agentes conectados e verificar se a desvinculação de associações de projetos mantém intactas as memórias pessoais essenciais.

## Disponibilidade e pré-requisitos

Os espaços de trabalho de projetos estão disponíveis para todas as contas pessoais na Memory Console em https://xmemo.dev/me#projects e por meio de perfis de cliente MCP suportados:

- Limite pessoal: os projetos são estritamente pessoais hoje; tentativas de criar um projeto com team_id são rejeitadas pelo servidor (HTTP 400). A documentação não faz promessas de suporte a projetos de equipe.
- Cotas sem limites: a criação de espaços de trabalho não é limitada por cotas numéricas de planos ou restrições artificiais de projetos. As contas provisionam espaços conforme necessário.
- Visualização particionada: a visualização "Atenção necessária" (Attention Needed) e as partições de memória de conhecimento (Knowledge) versus memória de trabalho (Working) operam se habilitadas para sua conta (o modo de avaliação de convergência fica desativado por padrão).
- Conectividade de agentes: agentes conectados acessam ferramentas de projetos correspondentes ao seu perfil de cliente, conforme contratado em config/mcp-documentation-contract.json.

## 1. Navegar até Projetos na Memory Console

Faça login em seu painel pessoal e abra https://xmemo.dev/me#projects. Na navegação à esquerda, selecione a seção Workspace e clique em Projects. O cabeçalho do painel anuncia "Browse project workspaces, context, and project memories." e exibe métricas principais para Total Projects, Active, Attention Needed e Archived.

```text
https://xmemo.dev/me#projects
Workspace -> Projects -> Total Projects (0) | Active (0) | Attention Needed (—) | Archived (0)
```

## 2. Provisionar um novo espaço de trabalho de projeto pessoal

Clique em Create New Project na área de ação superior para abrir a caixa de diálogo do espaço de trabalho:

- Nome do projeto: insira um nome de projeto descritivo (por exemplo, "Incident Response Automation"). O campo indica "Required, 1-128 characters." e valida contra caracteres de controle e separadores de caminho (/ ou \).
- Visualização do identificador do projeto: revise o identificador prévio (#incident-response-automation). O texto de ajuda confirma: "Non-authoritative preview. The backend server assigns the authoritative project key."
- Descrição: opcionalmente, insira uma declaração de escopo de até 2000 caracteres (por exemplo, "Operational runbooks, triage checklists, and automated incident response workflows.").
- Envio: clique em Create Project. O servidor atribui o identificador canônico e abre a visualização detalhada do projeto.

## 3. Associar memórias, TODOs e decisões

Uma vez provisionado o espaço de trabalho, preencha-o com contexto delimitado, tarefas pendentes e decisões de arquitetura:

- Associar uma memória: escreva uma memória sintética de runbook operacional delimitada ao projeto (scope: "incident-response-automation"): "Runbook policy: P0 production outages trigger immediate secondary on-call escalation after 15 minutes of unacknowledged alerts."
- Registrar um TODO: na visualização detalhada do projeto ou por meio de um agente, adicione uma tarefa: "Draft post-incident review template for payment gateway timeouts."
- Registrar uma decisão: registre uma decisão arquitetural: "Use PagerDuty webhook adapter for primary incident ingestion."
- Inspecionar métricas principais: a barra superior reflete os totais em tempo real: Memories: 1, Open TODOs: 1, Decisions: 1.

```ts
await client.remember(
  "Runbook policy: P0 production outages trigger immediate secondary on-call escalation after 15 minutes of unacknowledged alerts.",
  {
    path: "projects/incident-response-automation/runbooks/p0-escalation",
    scope: "incident-response-automation",
  },
);
```

## 4. Verificar a recuperação contextual do agente

Conecte um cliente de agente autorizado para verificar se a recuperação de projetos retorna os registros delimitados sem ruído entre projetos:

- Cursor ou Ordinary Full: agentes invocam get_project_context(project_id="incident-response-automation") para recuperar memórias ativas, TODOs pendentes e decisões registradas.
- ChatGPT ou Generic Public: agentes invocam get_project_summary(project_id="incident-response-automation") ou open_project_workspace para inspecionar o status de resumo.
- Widget interativo do ChatGPT: o widget interativo na conversa aberto por open_project_workspace fornece cartões de tarefas diretamente no diálogo; ele é distinto da Memory Console web completa em https://xmemo.dev/me#projects.

```json
{
  "project_id": "incident-response-automation",
  "status": "active",
  "memories_count": 1,
  "open_todos": 1,
  "decisions": 1,
  "summary": "Operational runbooks, triage checklists, and automated incident response workflows."
}
```

## 5. Desvincular memória e verificar remoção não destrutiva

Verifique se a remoção de uma memória de projeto desassocia o espaço de trabalho enquanto preserva o registro subjacente de memória pessoal:

- Abrir gaveta de memória: na lista de memórias do projeto, selecione o runbook operacional para exibir a gaveta de detalhes.
- Iniciar remoção: clique em Remove from Project nas ações da gaveta.
- Confirmar desvinculação: a caixa de diálogo abre com o cabeçalho "Remove from Project" e subtítulo "This memory will be disassociated from this project workspace.". Observe o aviso: "The memory content remains in your personal memory archive, but will no longer appear in this project context."
- Executar confirmação: clique em Remove. A contagem de memória do projeto diminui para 0.
- Verificar persistência global: navegue até o seu arquivo de memória pessoal (/me#memory) e confirme se a memória do runbook permanece intacta e recuperável.

## Resultado observável

Após concluir este fluxo de trabalho, seu espaço demonstra isolamento operacional completo:

- Status do espaço de trabalho: o projeto é listado em projetos ativos (Active) com o slug canônico #incident-response-automation.
- Isolamento contextual: agentes conectados consultam o contexto do projeto e recebem fatos delimitados sem contaminação de projetos não relacionados.
- Segurança dos dados: desvincular registros de memória de um espaço de trabalho reduz com sucesso os totais do projeto, mantendo os registros de memória pessoal permanentemente no seu arquivo.

## O que os agentes podem acessar

A disponibilidade de ferramentas para agentes depende estritamente do perfil de cliente configurado em config/mcp-documentation-contract.json:

- Perfis chatgpt-public, generic-public e public-only: expõem project, get_project_summary e open_project_workspace.
- Perfil claude-plugin: expõe project e get_project_context.
- Perfis cursor-plugin e ordinary-full: expõem get_project_context, update_project_todo e update_project_decision.
- Limites de perfil: outros perfis de cliente não expõem ferramentas de projeto. Tentar chamar ferramentas não contratadas resultará em rejeições de descoberta de ferramentas.

## Limites de compartilhamento e ciclo de vida

Os espaços de trabalho de projetos impõem limites operacionais e de dados explícitos:

- Limite pessoal: todos os espaços de trabalho são estritamente pessoais hoje. Espaços de trabalho de equipe não são suportados e solicitações fornecendo team_id falham na validação.
- Estados do ciclo de vida: o explorador de memória categoriza registros nos status Active, Superseded, Expired e Archived.
- Partições de curadoria: se habilitadas para sua conta, os espaços de trabalho oferecem partições de memória de conhecimento (Knowledge) e de trabalho (Working). A partição Knowledge mantém convenções persistentes; a partição Working armazena o estado transitório de sessão.
- Distinção de bases de conhecimento: as partições de projetos categorizam memórias episódicas de conversas. Em contraste, as bases de conhecimento fornecem gerenciamento formal e versionado de documentos com instantâneos multirrevisão. Para documentação com curadoria, consulte /docs/concepts/knowledge-bases.
- Limite de cota: espaços de trabalho de projetos pessoais não possuem cotas numéricas.

## Recuperação de falhas

Casos extremos comuns e ações de recuperação:

- Nome de projeto duplicado (HTTP 409): o servidor rejeita nomes duplicados com "A project with this name or identifier already exists in your workspace.". Forneça um nome de projeto distinto.
- Nome de projeto inválido (HTTP 400): nomes de projetos não podem conter barras (/ ou \), exceder 128 caracteres ou usar tokens reservados (_project, ., ..). Corrija o nome na caixa de diálogo de criação.
- Incompatibilidade de ferramentas do perfil de cliente: se um agente não encontrar get_project_context, verifique o perfil de cliente ativo. O perfil chatgpt-public expõe get_project_summary, enquanto get_project_context é exposto sob cursor-plugin e ordinary-full.
- Conflito de versão (HTTP 409): se outra sessão modificar o projeto ou a memória simultaneamente, a gaveta exibirá "Modified elsewhere, please reload" ao lado de um botão Reload. Clique em Reload para atualizar o estado.

## Referência relacionada

Para recursos complementares e referências técnicas, consulte:

- Referência de conceitos de projetos: detalhes arquiteturais e convenções de escopo em /docs/concepts/projects.
- Guia da Memory Console: apresentação completa da interface web em /docs/guides/memory-console.
- Guia de bases de conhecimento: gerenciamento de documentação de referência com curadoria em /docs/concepts/knowledge-bases.
- API REST de projetos: endpoints programáticos autenticados em /docs/api/projects.

## Usuário do ChatGPT

Dê ao ChatGPT acesso duradouro às suas preferências do XMemo, fatos do projeto, decisões e TODOs sem colar tokens bearer no chat.

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.

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.

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

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.

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.

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.

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

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.

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.

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.

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

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.

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.

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.

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.