Memoria

Memoria

A Memória que Sua IA Não Tem.

Um servidor MCP que impede sua IA de quebrar código ao revelar dependências ocultas de arquivos por meio de forense de git.

⚡ Instalação Rápida

Instalação com Um Clique (Smithery)

Clique no selo acima para instalar o Memoria com um clique via Smithery.

Configuração Rápida de Copiar e Colar

Adicione isto ao seu arquivo de configuração MCP (funciona com Claude, Cursor, Windsurf, Cline):

{
  "mcpServers": {
    "memoria": {
      "command": "npx",
      "args": ["-y", "@byronwade/memoria"]
    }
  }
}

Comandos de Uma Linha no Terminal

# Claude Desktop
$config = "$env:APPDATA\Claude\claude_desktop_config.json"
$json = if(Test-Path $config){Get-Content $config | ConvertFrom-Json}else{@{}}
$json.mcpServers = @{memoria=@{command="npx";args=@("-y","@byronwade/memoria")}}
$json | ConvertTo-Json -Depth 10 | Set-Content $config

# Claude Desktop (requires jq: brew install jq)
echo '{"mcpServers":{"memoria":{"command":"npx","args":["-y","@byronwade/memoria"]}}}' | \
  jq -s '.[0] * .[1]' ~/Library/Application\ Support/Claude/claude_desktop_config.json - > tmp.json && \
  mv tmp.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

Então reinicie sua ferramenta de IA. É isso!

Por que Memoria?

Você pede à sua IA para refatorar um arquivo. Ela faz um trabalho perfeito. Você executa seu aplicativo. Ele quebra.

Por quê? Algum outro arquivo dependia da implementação antiga - mas não há import entre eles, então a IA não sabia.

Memoria resolve isso. Ele analisa o histórico do git para encontrar arquivos que mudam juntos, mesmo sem imports diretos.

Without Memoria:                        With Memoria:
─────────────────                       ─────────────
You: "Update route.ts"                  You: "Update route.ts"
AI: "Done!" ✅                           Memoria: "⚠️ 85% coupled with billing.tsx"
Result: 💥 CRASH                         AI: "I'll update both files"
                                        Result: ✅ Works

Privado e Local

Memoria roda 100% na sua máquina.

• Nenhum código é enviado para a nuvem
• Nenhuma chave de API é necessária
• Funciona offline
• Analisa sua pasta local .git diretamente

Seu código nunca sai do seu computador.

Instalação

Escolha sua ferramenta de IA:

Ferramenta	Comando de Uma Linha	Arquivo de Configuração
	npx @anthropic/claude-code mcp add memoria -- npx -y @byronwade/memoria	Veja abaixo
	claude mcp add memoria -- npx -y @byronwade/memoria	Automático
	mkdir -p .cursor && echo '{"mcpServers":{"memoria":{"command":"npx","args":["-y","@byronwade/memoria"]}}}' > .cursor/mcp.json	.cursor/mcp.json
	Configuração manual	~/.codeium/windsurf/mcp_config.json
	Configuração manual	~/.continue/config.json
	Interface de Configurações	Configurações MCP do Cline

npx @anthropic/claude-code mcp add memoria -- npx -y @byronwade/memoria

{
  "mcpServers": {
    "memoria": {
      "command": "npx",
      "args": ["-y", "@byronwade/memoria"]
    }
  }
}

claude mcp add memoria -- npx -y @byronwade/memoria

mkdir -p .cursor && echo '{"mcpServers":{"memoria":{"command":"npx","args":["-y","@byronwade/memoria"]}}}' > .cursor/mcp.json

{
  "mcpServers": {
    "memoria": {
      "command": "npx",
      "args": ["-y", "@byronwade/memoria"]
    }
  }
}

{
  "mcpServers": {
    "memoria": {
      "command": "npx",
      "args": ["-y", "@byronwade/memoria"]
    }
  }
}

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@byronwade/memoria"]
        }
      }
    ]
  }
}

{
  "mcpServers": {
    "memoria": {
      "command": "npx",
      "args": ["-y", "@byronwade/memoria"]
    }
  }
}

{
  "mcpServers": {
    "memoria": {
      "command": "npx",
      "args": ["-y", "@byronwade/memoria"]
    }
  }
}

⚠️ Após configurar, reinicie sua ferramenta de IA.

Verificar Instalação

Após reiniciar, pergunte à sua IA:

"What MCP tools do you have available?"

Você deve ver analyze_file e ask_history na lista.

Ou teste diretamente:

"Use the analyze_file tool on any file in this project"

Uso

Peça à sua IA para analisar um arquivo antes de fazer alterações:

"Analyze src/api/stripe/route.ts before I refactor it"

Memoria retorna:

• Arquivos acoplados - Arquivos que mudam juntos com frequência
• Pontuação de risco - Quão propenso a bugs este código é historicamente
• Dependências desatualizadas - Arquivos acoplados que podem precisar de atualização
• Evidências - Diffs de código reais mostrando por que os arquivos estão relacionados

Comandos CLI

Memoria inclui uma CLI completa para análise manual - as mesmas capacidades que sua IA usa:

# Full forensic analysis (same as AI's analyze_file)
memoria analyze src/index.ts

# Quick risk assessment
memoria risk src/api/route.ts

# Show coupled files
memoria coupled src/auth.ts

# Find files that import the target
memoria importers src/types.ts

# Search git history (same as AI's ask_history)
memoria history "setTimeout" src/utils.ts
memoria history "fix" --type=message

Opções de Saída

# JSON output for scripting/CI
memoria analyze src/index.ts --json

# Pipe to other tools
memoria risk src/api/route.ts --json | jq '.riskScore'

Exemplo de Saída

$ memoria analyze src/index.ts

Forensics for `index.ts`

RISK: 45/100 (MEDIUM)
Risk factors: High volatility (38%) • Coupled (5 files) • 3 dependents

VOLATILITY
  Panic score: 38% | Commits: 24
  Top author: Dave (72%)

COUPLED FILES
  85% billing/page.tsx [schema]
      References: billing_records table. Schema changes may break queries.
  90% index.test.ts [test]
      Test file matches naming pattern. Update when changing exports.
  75% config.ts [env]
      Shares env vars: API_KEY, DATABASE_URL
  65% hooks/useData.ts [api]
      Calls endpoint: GET /api/data

STATIC DEPENDENTS
  - [ ] Check `cli.ts`
  - [ ] Check `server.ts`
  - [ ] Check `utils.ts`

Analysis completed in 142ms

Configuração (Opcional)

Crie um .memoria.json na raiz do seu projeto para personalizar limites:

{
  "thresholds": {
    "couplingPercent": 20,
    "driftDays": 14,
    "analysisWindow": 100
  },
  "ignore": [
    "**/*.lock",
    "dist/",
    "legacy/**"
  ],
  "panicKeywords": {
    "postmortem": 3,
    "incident": 3,
    "p0": 3
  },
  "riskWeights": {
    "volatility": 0.35,
    "coupling": 0.30,
    "drift": 0.20,
    "importers": 0.15
  }
}

Como Funciona

Motor de Volatilidade

Escaneia commits por palavras-chave de pânico (fix, bug, revert, urgent, hotfix) com decadência temporal - bugs recentes importam mais que os antigos. Também rastreia o Fator de Ônibus (quem é dono do código).

Motor de Entrelaçamento

Encontra arquivos que mudam juntos >15% do tempo. Revela dependências implícitas que imports não mostram.

Motor Sentinela

Detecta quando arquivos acoplados estão >7 dias fora de sincronia. Sinaliza dependências desatualizadas antes que causem bugs.

Motor de Importação Estática

Usa git grep para encontrar arquivos que importam o alvo - mesmo para arquivos novos sem histórico git.

Pesquisa de Histórico (O Arqueólogo)

Pesquise o histórico do git para entender por que o código foi escrito. Resolve o problema da "Cerca de Chesterton" antes de deletar aquele código de aparência estranha.

Acoplamento de Documentação

Encontra arquivos markdown que referenciam suas funções/tipos exportados. Captura atualizações de README necessárias quando o formato de saída muda.

Acoplamento de Tipos

Usa git pickaxe (git log -S) para encontrar arquivos que compartilham definições de tipos - mesmo sem imports diretos.

Acoplamento de Conteúdo

Encontra arquivos que compartilham literais de string (mensagens de erro, constantes) que devem permanecer em sincronia.

Acoplamento de Arquivos de Teste

Descobre automaticamente arquivos de teste que correspondem a convenções de nomenclatura (*.test.*, *.spec.*, *_test.*, etc.) e arquivos mock/fixture - sem extensões codificadas.

Acoplamento de Variáveis de Ambiente

Encontra arquivos que compartilham variáveis de ambiente ALL_CAPS_UNDERSCORE (API_KEY, DATABASE_URL, etc.) - funciona em qualquer linguagem.

Acoplamento de Schema/Modelo

Detecta definições de schema de banco de dados (SQL, Prisma, TypeORM, Mongoose) e encontra arquivos que consultam essas tabelas/modelos.

Acoplamento de Endpoints de API

Encontra código de cliente que chama endpoints de API definidos em arquivos de rota. Captura mudanças na forma da resposta que quebram consumidores.

Acoplamento de Cadeia de Re-Exportação

Detecta arquivos barrel (index.ts) que re-exportam seu módulo e encontra importadores transitivos através desses barrels.

Exemplo de Saída

# Forensics: `route.ts`

**RISK: 65/100** — HIGH
45% volatility · 3 coupled · 8 dependents · 1 stale

> Proceed carefully. Check all coupled files and update stale dependencies.

---

## Coupled Files

**`billing/page.tsx`** — 85% (schema)
> These files share type definitions. If you modify types in one, update the other to match.
  + interface SubscriptionUpdated
  - oldStatus: string

**`route.test.ts`** — 90% [test]
> Test file for this module. Update when changing exports.

**`services/stripe.ts`** — 75% [env]
> Shares env vars: STRIPE_KEY, STRIPE_SECRET

**`README.md`** — 70% [docs]
> Documentation references: generateReport, SubscriptionStatus

**`types/billing.ts`** — 65% [type]
> Shared types: SubscriptionUpdated, PaymentStatus

**`features/billing/index.ts`** — 60% [transitive]
> Re-exports this file. Changes propagate through this barrel.

---

## Static Dependents

These files import `route.ts`. API changes require updating them.

- [ ] `src/components/SubscriptionCard.tsx`
- [ ] `src/hooks/useSubscription.ts`

---

## Pre-flight Checklist

- [ ] Modify `route.ts`
- [ ] Update `billing/page.tsx` (schema)
- [ ] Update `tests/stripe.test.ts` — stale 12d

---

## File History

**Volatile** — 45% panic score
**Expert:** Dave (90% of commits)

Modo Piloto Automático

Quer que sua IA verifique o Memoria automaticamente antes de cada edição? Instale os arquivos de regras:

# Install globally first
npm install -g @byronwade/memoria

# Then in your project directory:
memoria init --all

Isso instala arquivos de regras que dizem à sua IA para sempre chamar analyze_file antes de editar código.

O que é Instalado

Comportamento de Mesclagem Inteligente

memoria init é seguro de executar várias vezes - não sobrescreverá suas regras existentes:

# First run - creates or appends
memoria init --cursor
#   ✓ Created .cursor/rules/memoria.mdc

# Second run - skips (already installed)
memoria init --cursor
#   ⊘ Skipped .cursor/rules/memoria.mdc (already has Memoria rules)
#   Use --force to update existing Memoria rules.

# Force update to latest version
memoria init --cursor --force
#   ✓ Updated .cursor/rules/memoria.mdc (--force)

Detecção Automática

Executar memoria init sem bandeiras detectará automaticamente quais ferramentas você está usando:

memoria init
# Detected: Cursor, Claude Code
# Installing Memoria rules...
#   ✓ Created .cursor/rules/memoria.mdc
#   ✓ Appended to .claude/CLAUDE.md (preserved existing content)
# ✓ Installed/updated 2 rule file(s)

Agora o Memoria atua como uma proteção obrigatória para cada edição.

Desempenho

Memoria é otimizado para velocidade e uso mínimo de tokens:

Detalhamento dos Motores

Execute benchmarks você mesmo:

npm run build
npx tsx benchmarks/run-benchmarks.ts

Requisitos

• Node.js 18+
• Repositório Git com histórico de commits
• Ferramenta de IA compatível com MCP

Layout do Monorepo (Turbo)

• apps/mcp-server — servidor MCP e pacote npm (publica @byronwade/memoria)
• apps/api — stub de backend de API (placeholder HTTP Node)
• apps/web — stub de frontend web
• packages — bibliotecas compartilhadas (futuro)

Desenvolvimento

npm install
npm run build                     # turbo build across workspaces
npm test                          # turbo test (runs vitest in mcp-server)

# Focus on a single app/package
npx turbo run build --filter=@byronwade/memoria
npx turbo run dev --filter=@byronwade/memoria

Solução de Problemas

npm install -g @byronwade/memoria

{
  "mcpServers": {
    "memoria": {
      "command": "memoria"
    }
  }
}

"args": ["-y", "@byronwade/memoria"]

Ainda preso? Abra um problema com sua configuração e mensagem de erro.

Licença

MIT

Quando o Memoria te salvar de uma regressão, nos avise.