project-memory MCP — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

Cânon de quatro arquivos: bugs.md, Decisions.md, key_facts.md, Issues.md
Claude os lê antes de propor mudanças arquitetônicas
Três escopos de instalação: global (~/.claude/skills), projeto (.claude/skills), espaço de trabalho
Instalável via skilz (pip) ou cópia simples
Sem banco de dados – apenas Markdown, você pode comparar e revisar

Demo ao vivo

Como fica na prática

project-memory-skill.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

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

{
  "mcpServers": {
    "project-memory-skill": {
      "command": "pip",
      "args": [
        "install",
        "skilz",
        "&&",
        "skilz",
        "install",
        "SpillwaveSolutions_project-memory/project-memory"
      ],
      "_inferred": false
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "project-memory-skill": {
      "command": "pip",
      "args": [
        "install",
        "skilz",
        "&&",
        "skilz",
        "install",
        "SpillwaveSolutions_project-memory/project-memory"
      ],
      "_inferred": false
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "project-memory-skill": {
      "command": "pip",
      "args": [
        "install",
        "skilz",
        "&&",
        "skilz",
        "install",
        "SpillwaveSolutions_project-memory/project-memory"
      ],
      "_inferred": false
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "project-memory-skill": {
      "command": "pip",
      "args": [
        "install",
        "skilz",
        "&&",
        "skilz",
        "install",
        "SpillwaveSolutions_project-memory/project-memory"
      ],
      "_inferred": false
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "project-memory-skill",
      "command": "pip",
      "args": [
        "install",
        "skilz",
        "&&",
        "skilz",
        "install",
        "SpillwaveSolutions_project-memory/project-memory"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "project-memory-skill": {
      "command": {
        "path": "pip",
        "args": [
          "install",
          "skilz",
          "&&",
          "skilz",
          "install",
          "SpillwaveSolutions_project-memory/project-memory"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add project-memory-skill -- pip install skilz && skilz install SpillwaveSolutions_project-memory/project-memory

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: project-memory

Bootstrap memória do projeto em uma base de código existente

👤 Equipes cansadas de reexplicar o mesmo contexto ao agente ⏱ ~15 min beginner

Quando usar: Você está usando o Claude Code neste repositório, mas o contexto é redefinido a cada sessão.

Pré-requisitos

Python 3.10+ para instalador skilz — pyenv ou sistema Python

Fluxo

Instalar no escopo do projeto

pip instalar skilz && skilz instalar SpillwaveSolutions_project-memory/project-memory --scope projeto✓ Copiado

→ .claude/skills/project-memory/SKILL.md aparece
Execute o comando de inicialização

/project-memory — inicializa os quatro arquivos deste repositório.✓ Copiado

→ docs/project_notes/ criado com os quatro arquivos canônicos
Semeie decisões.md com 2–3 opções conhecidas

Adicione ADRs para nossa escolha de ORM, nossa convenção de tratamento de erros e nosso executor de CI.✓ Copiado

→ Três entradas ADR organizadas

Resultado: Claude agora tem um cérebro persistente e revisável para este repositório.

Armadilhas

Comprometendo key_facts.md com segredos — A habilidade sinaliza explicitamente key_facts.md como 'não confidencial' - nunca coloque credenciais lá

Combine com: memory-bank-mcp

Capture a causa raiz de um bug para que ele nunca mais volte

👤 Engenheiros de plantão apagando um incêndio ⏱ ~5 min beginner

Quando usar: Você acabou de consertar algo complicado e quer que a lição dure.

Fluxo

Peça ao Claude para gravar

Adicione isto ao bugs.md – o erro foi NoneType em billing.retry; causa raiz: cache de chave de idempotência obsoleto; prevenção: TTL no cache.✓ Copiado

→ Nova entrada bugs.md com causa raiz + prevenção

Resultado: Um catálogo de bugs que rende dividendos na próxima vez que um sintoma semelhante aparecer.

Armadilhas

Escrevendo o sintoma em vez da causa — Forçar a entrada a ter uma seção de 'Causa raiz' e 'Prevenção' - não apenas 'o que eu consertei'

Combine com: github

Deixe Claude consultar o Decisions.md antes de sugerir uma refatoração

👤 Equipes que odeiam litigar novamente decisões acertadas com seu agente ⏱ ~10 min beginner

Quando usar: Seu agente continua propondo estruturas/padrões aos quais a equipe já disse não.

Fluxo

Certifique-se de que a decisão esteja em Decisions.md

Registro: 'Usamos o padrão Repository, não o Active Record. Justificativa: <x>.'✓ Copiado

→ Limpar ADR em Decisions.md
Peça o refatorador

Proponha um refatorador de src/billing/ — respeite nossas decisões.md.✓ Copiado

→ A proposta faz referência à decisão do Repositório e não sugere Active Record

Resultado: Menos propostas sem saída que são rejeitadas na revisão.

Combine com: git

Combinações

Combine com outros MCPs para 10× de alavancagem

project-memory-skill + memory-bank-mcp

Use project-memory para os quatro arquivos canônicos selecionados, memory-bank-mcp para memória de trabalho de forma livre entre projetos

Escreva ADRs estruturados em Decisions.md; despejar notas de sessão brutas no banco de memória.✓ Copiado

project-memory-skill + github

Depois de mesclar um PR, atualize Decisions.md e Issues.md como parte da descrição do PR

Abra o PR e inclua a diferença Decisions.md na descrição.✓ Copiado

project-memory-skill + git

Revise as diferenças de memória antes de se comprometer a mantê-las honestas

git diff docs/project_notes/ — leia antes de confirmar; consertar qualquer coisa enganosa.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
/project-memory	subcommand: init\|add-bug\|add-decision\|add-fact\|log-issue	Inicialize os arquivos e registre novas entradas	0

Custo e limites

O que custa rodar

Cota de API: Nenhum
Tokens por chamada: Depende de quanto dos quatro arquivos Claude carrega; mantenha as entradas curtas
Monetário: Livre
Dica: Prefira entradas curtas e datadas a narrativas longas – Claude as examina em todas as sessões, então o tamanho é importante.

Segurança

Permissões, segredos, alcance

Armazenamento de credenciais: Explicitamente: key_facts.md é apenas para configurações não confidenciais. Mantenha os segredos em um ambiente ou cofre, não aqui.

Saída de dados: Arquivos locais; nenhuma atividade de rede da habilidade em si

Se você enviar docs/project_notes/ para um repositório público, lembre-se de que Claude pode ter registrado detalhes internos – revise antes de enviar.
Não permita que os agentes sejam anexados automaticamente ao Decisions.md sem revisão; é aí que o contexto obsoleto ou errado corrói todo o sistema.

Solução de problemas

Erros comuns e correções

Comando /project-memory não reconhecido

Habilidade não instalada no escopo esperado. Reinstale com skilz e reinicie Claude.

Verificar: ls ~/.claude/skills/project-memory/ or .claude/skills/project-memory/

Claude ignora decisões.md

Certifique-se de que o Decisions.md tenha entradas claras no estilo ADR com cabeçalhos 'Decision' e 'Rationale'; marcadores vagos são ignorados.

Verificar: head docs/project_notes/decisions.md

Os arquivos continuam crescendo

Arquivar trimestralmente – mova entradas antigas para docs/project_notes/archive/ para que os arquivos ativos permaneçam digitalizáveis.

Verificar: wc -l docs/project_notes/*.md

Alternativas

project-memory vs. outros

Alternativa	Quando usar	Troca
memory-bank-mcp	Você deseja que a memória entre projetos seja acessível por ferramenta, não por arquivos	Mais flexibilidade, menos visível nas análises de RP
codebase-memory	Você quer um gráfico de símbolos do código, não notas narrativas	Camada diferente de memória
marm-systems	Você quer uma estrutura de memória mais elaborada	Configuração mais pesada

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills