Memory Graph

Um servidor do Protocolo de Contexto de Modelo (MCP) baseado em grafo que fornece memória persistente para agentes de codificação de IA. Originalmente construído para o Claude Code, o MemoryGraph funciona com qualquer agente de codificação compatível com MCP. Armazene padrões de desenvolvimento, acompanhe relacionamentos e recupere conhecimento contextual entre sessões e projetos.

GitHub

252

Documentação

MemoryGraph

CLI de Memória Baseada em Grafos para Agentes de Codificação de IA

Um sistema de memória baseado em grafos que dá aos agentes de codificação de IA memória persistente.
Armazene padrões, rastreie relacionamentos, recupere conhecimento entre sessões.

Usando com Agentes de Codificação

Agentes de codificação já executam comandos de shell, então podem usar o MemoryGraph diretamente. Dois passos: instale globalmente, depois adicione instruções.

Instalação

cd memory-graph/ts && bun install && bun link
# or: bun build src/cli.ts --compile --outfile ~/.local/bin/memorygraph
memorygraph stats  # verify

memorygraph agora está disponível a partir de qualquer diretório. Os dados persistem em ~/.memorygraph/.

Adicionar Instruções do Agente

Cole isto no arquivo de instruções do seu agente (~/.claude/CLAUDE.md, .cursorrules, .windsurfrules ou AGENTS.md):

## Memory
`memorygraph` CLI is installed. Use it for persistent memory across sessions.

Before work: `memorygraph recall --query "<task>" --limit 10` and `memorygraph briefing`
On decisions/fixes: `memorygraph store --type solution --title "<title>" --content "<what>" --tags "<component>,fix"`
On errors: `memorygraph store --type error --title "<error>" --content "<details>" --tags "<component>,error"`
Link: `memorygraph link <from-id> <to-id> SOLVES --strength 0.8`
Session end: `memorygraph store --type conversation --title "Session: <topic>" --content "<summary>" --tags "<tags>"`
Types: solution | problem | code_pattern | fix | error | workflow | command | technology
Tags: lowercase, hyphenated, include component (auth, database, cli), 2-5 per memory
Do NOT wait to be asked. Store automatically on triggers.

Exemplo de Sessão

# Start: load context
memorygraph recall --query "authentication redis" --limit 10
memorygraph briefing

# Fix a bug: store problem + solution, link them
memorygraph store --type problem --title "Auth token expiry too short" --content "Tokens expiring after 1h" --tags "auth,bug"
# → abc-123
memorygraph store --type solution --title "Extend token expiry to 24h" --content "Changed JWT expiry, added refresh rotation" --tags "auth,fix" --importance 0.8
# → def-456
memorygraph link def-456 abc-123 SOLVES --strength 0.9

# End: store summary
memorygraph store --type conversation --title "Session: auth token fix" --content "Fixed token expiry, added refresh rotation" --tags "auth,session-summary"

Configuração Multi-Projeto

Todos os projetos compartilham ~/.memorygraph/falkordblite.db por padrão. Para isolar por projeto:

export MEMORY_FALKORDBLITE_PATH=~/.memorygraph/my-project.falkor
# or tag memories with project name and filter:
memorygraph search --query "auth" --tags my-project

Solução de Problemas

Agente não está usando comandos: Use "REQUIRED"/"MUST" nas instruções, inclua comandos exatos
Comando não encontrado: bun link de ts/, ou garanta que ~/.local/bin esteja no PATH
Memórias não persistindo: memorygraph config para verificar o caminho, memorygraph health para confirmar

Por que MemoryGraph?

Relacionamentos em Grafo Fazem a Diferença

Armazenamento plano (CLAUDE.md, armazenamentos vetoriais) mantém memórias como entradas isoladas. O armazenamento em grafo as conecta:

[timeout_fix] --CAUSES--> [memory_leak] --SOLVED_BY--> [connection_pooling]
     |                                                        |
     +------------------SUPERSEDED_BY------------------------+

Consulta: "O que aconteceu com a lógica de retry?" retorna a cadeia causal completa, não apenas memórias individuais.

Quando Usar o Quê

Use CLAUDE.md / AGENTS.md Para	Use MemoryGraph Para
"Sempre use indentação de 2 espaços"	"Da última vez usamos 4 espaços, quebrou o linter"
"Execute testes antes de commitar"	"Os testes de autenticação falharam por causa de X, corrigido por Y"
Regras estáticas, diretrizes primárias	Aprendizados dinâmicos com relacionamentos

Comandos CLI

Operações de Memória

Comando	Finalidade	Exemplo
`store`	Armazenar uma nova memória	`store --type solution --title "Fix" --content "..." --tags redis,fix`
`get`	Obter uma memória por ID	`get <memory-id>`
`update`	Atualizar uma memória existente	`update <id> --title "New title"`
`delete`	Excluir uma memória	`delete <memory-id>`
`search`	Pesquisar com filtros	`search --query "timeout" --tags redis --limit 10`
`recall`	Recuperação em linguagem natural	`recall --query "authentication security"`
`related`	Obter memórias relacionadas	`related <id> --types SOLVES,CAUSES --max-depth 2`
`link`	Criar um relacionamento	`link <from-id> <to-id> SOLVES --strength 0.8`

Busca por Contexto

Comando	Finalidade
`context-search`	Pesquisar relacionamentos por tipo, força ou texto de contexto
`contextual-search`	Pesquisar dentro dos itens relacionados de uma memória

Inteligência

Comando	Finalidade
`entities`	Extrair entidades (arquivos, funções, classes, tecnologias) de uma memória
`patterns`	Encontrar problemas semelhantes e sugerir padrões
`context`	Obter recuperação inteligente de contexto com correspondência de entidades e palavras-chave

Análises

Comando	Finalidade
`stats`	Estatísticas do banco de dados (contagem de memórias, tipos, relacionamentos)
`activity`	Resumo de atividade recente com problemas não resolvidos
`visualize`	Dados de visualização do grafo (nós e arestas)
`similarity`	Analisar similaridade de soluções para uma determinada memória
`learning`	Recomendar caminhos de aprendizado para um tópico
`gaps`	Identificar lacunas de conhecimento (problemas não resolvidos, conexões ausentes)

Proativo

Comando	Finalidade
`briefing`	Gerar um briefing de sessão com atividade recente e problemas em aberto
`predict`	Prever o que pode ser necessário com base no contexto atual
`warn`	Alertar sobre problemas potenciais (abordagens obsoletas, erros conhecidos)
`outcome`	Registrar um resultado para uma memória (acompanhamento de sucesso/falha)

Integração

Comando	Finalidade
`capture`	Capturar contexto de tarefa do ambiente atual
`analyze-project`	Analisar a base de código do projeto atual
`workflow`	Acompanhar ou sugerir melhorias no fluxo de trabalho

Temporal

Comando	Finalidade
`as-of`	Consultar relacionamentos como existiam em um momento específico
`history`	Obter histórico completo de relacionamentos de uma memória
`changes`	Mostrar mudanças de relacionamento desde um timestamp

Gerenciamento de Dados

Comando	Finalidade
`export`	Exportar para JSON ou Markdown
`import`	Importar de JSON
`migrate`	Migrar entre backends
`health`	Executar uma verificação de saúde
`config`	Mostrar configuração atual

Backends

Backend	Tipo	Config	Grafo Nativo	Zero-Config	Melhor Para
falkordblite (padrão)	Embutido	Caminho de arquivo	Cypher	Sim	Padrão, consultas de grafo sem servidor
sqlite	Embutido	Caminho de arquivo	Simulado	Sim	Fallback sem dependências
falkordb	Cliente-servidor	Host:porta	Cypher	Não	Produção de alto desempenho
memgraph	Cliente-servidor	URI Bolt	Cypher	Não	Análises em tempo real
cloud	Nuvem	Chave de API	Cypher	Não	Sincronização multi-dispositivo, compartilhamento em equipe

Configuração do Backend

# Use FalkorDBLite (default, zero-config)
bun run src/cli.ts stats

# Use SQLite
MEMORY_BACKEND=sqlite bun run src/cli.ts stats

# Use FalkorDB (client-server)
MEMORY_BACKEND=falkordb MEMORY_FALKORDB_HOST=localhost MEMORY_FALKORDB_PORT=6379 bun run src/cli.ts stats

# Use Memgraph
MEMORY_BACKEND=memgraph MEMORY_MEMGRAPH_URI=bolt://localhost:7687 bun run src/cli.ts stats

# Use Cloud
MEMORY_BACKEND=cloud MEMORYGRAPH_API_KEY=mg_your_key bun run src/cli.ts stats

Variáveis de Ambiente

Variável	Descrição	Padrão
`MEMORY_BACKEND`	Tipo de backend	`falkordblite`
`MEMORY_FALKORDBLITE_PATH`	Caminho do banco de dados FalkorDBLite	`~/.memorygraph/falkordblite.db`
`MEMORY_SQLITE_PATH`	Caminho do banco de dados SQLite	`~/.memorygraph/memory.db`
`MEMORY_FALKORDB_HOST`	Host do servidor FalkorDB	`localhost`
`MEMORY_FALKORDB_PORT`	Porta do servidor FalkorDB	`6379`
`MEMORY_MEMGRAPH_URI`	URI Bolt do Memgraph	`bolt://localhost:7687`
`MEMORYGRAPH_API_KEY`	Chave da API Cloud	-
`MEMORYGRAPH_API_URL`	URL da API Cloud	`https://graph-api.memorygraph.dev`
`MEMORY_TOOL_PROFILE`	Perfil da ferramenta (core ou extended)	`core`
`MEMORY_LOG_LEVEL`	Nível de log	`INFO`

Tipos de Memória

Tipo	Caso de Uso
`task`	Tarefas e itens de ação
`code_pattern`	Padrões de código recorrentes ou convenções
`problem`	Problemas ou desafios encontrados
`solution`	Soluções, decisões ou abordagens escolhidas
`project`	Contexto do projeto, ambiente, informações de configuração
`technology`	Escolhas e avaliações de tecnologia
`error`	Erros descobertos
`fix`	Correções aplicadas a erros
`command`	Comandos úteis ou trechos de CLI
`file_context`	Contexto sobre arquivos específicos
`workflow`	Descrições de fluxo de trabalho ou processos
`general`	Memórias de propósito geral
`conversation`	Resumos de conversas

Tipos de Relacionamento

Tipo	Significado
`RELATED_TO`	Conexão geral
`BUILDS_ON`	Nova memória estende uma mais antiga
`CONTRADICTS`	Nova memória substitui ou invalida uma mais antiga
`CONFIRMS`	Nova memória fornece evidência para uma mais antiga
`SOLVES`	Uma solução resolve um problema
`CAUSES`	Uma memória causa outra
`REQUIRES`	Uma memória depende de outra
`IMPROVES`	Uma melhoria em relação a uma abordagem existente
`REPLACES`	Substitui uma abordagem mais antiga
`DEPENDS_ON`	Dependência de fluxo de trabalho

Melhores Práticas de Memória

Fluxo de Trabalho de Sessão

# Start of session: recall recent context
bun run src/cli.ts recall --query "recent work" --limit 10

# During work: store decisions and patterns
bun run src/cli.ts store \
  --type solution \
  --title "Use JWT for auth" \
  --content "JWT tokens with 24h expiry, refresh token rotation" \
  --tags "auth,security,api" \
  --importance 0.8

# Link it to a prior decision
bun run src/cli.ts link <new-id> <prior-id> BUILDS_ON --strength 0.9

# End of session: store summary
bun run src/cli.ts store \
  --type conversation \
  --title "Session: auth refactor" \
  --content "Refactored auth middleware, added JWT, fixed token refresh bug" \
  --tags "auth,session-summary"

# Export backup
bun run src/cli.ts export --format json --output session-backup.json

Adicionar ao CLAUDE.md ou AGENTS.md

## Memory Protocol

### REQUIRED: Before Starting Work
You MUST use `recall` before any task. Query by project, tech, or task type.

### REQUIRED: Automatic Storage Triggers
Store memories on ANY of:
- Git commit: what was fixed/added
- Bug fix: problem + solution
- Architecture decision: choice + rationale
- Pattern discovered: reusable approach

### Memory Fields
- Type: solution | problem | code_pattern | fix | error | workflow
- Title: Specific, searchable
- Content: Accomplishment, decisions, patterns
- Tags: project, tech, category (required)
- Importance: 0.8+ critical, 0.5-0.7 standard, 0.3-0.4 minor
- Relationships: Link related memories when they exist

Arquitetura

Estrutura do Projeto

memory-graph/
├── ts/
│   ├── src/
│   │   ├── cli.ts              # CLI entry point (35+ commands)
│   │   ├── index.ts            # Library exports
│   │   ├── config.ts           # Configuration management
│   │   ├── database.ts         # Database interface
│   │   ├── models.ts           # Data models and schemas
│   │   ├── backends/           # Backend implementations
│   │   │   ├── falkordb-shared.ts  # Shared FalkorDB base class
│   │   │   ├── falkordblite.ts     # Embedded FalkorDBLite
│   │   │   ├── falkordb.ts         # Client-server FalkorDB
│   │   │   ├── bolt-shared.ts      # Shared Bolt protocol base
│   │   │   ├── memgraph.ts         # Memgraph (Bolt protocol)
│   │   │   ├── sqlite.ts           # SQLite fallback
│   │   │   ├── cloud.ts            # Cloud REST API
│   │   │   └── factory.ts          # Backend factory
│   │   ├── tools/              # CLI tool handlers
│   │   ├── intelligence/       # Entity extraction, pattern recognition, context retrieval
│   │   ├── analytics/          # Graph visualization, similarity, learning paths
│   │   ├── proactive/          # Session briefing, predictions, outcome learning
│   │   ├── integration/        # Context capture, project analysis, workflow tracking
│   │   ├── migration/          # Backend-to-backend migration
│   │   ├── sdk/                # Cloud API client SDK
│   │   └── utils/              # Export/import, validation, helpers
│   ├── tests/                  # 97 tests
│   └── package.json
├── docs/                       # Documentation
└── CLAUDE.md                   # Agent instructions

Compilação

cd ts
bun install
bun test                    # Run tests
npx tsc --noEmit            # Type check
bun build src/cli.ts --compile --outfile memorygraph  # Compile binary

Importação / Migração

# Import from JSON export
bun run src/cli.ts import --input backup.json --skip-duplicates

# Migrate between backends
bun run src/cli.ts migrate --to sqlite --to-path ./local.db
bun run src/cli.ts migrate --to falkordblite --to-path ./graph.falkor --no-verify
bun run src/cli.ts migrate --to memgraph --to-uri bolt://localhost:7687

SDK

O SDK TypeScript fornece um cliente para a API Cloud do MemoryGraph:

import { MemoryGraphClient } from "memorygraph/sdk";

const client = new MemoryGraphClient({ apiKey: "mg_..." });

const memory = await client.createMemory({
  type: "solution",
  title: "Fixed timeout issue",
  content: "Used exponential backoff with retries",
  tags: ["redis", "timeout"],
});

Licença

Licença MIT - veja LICENSE.

Comece simples. Atualize quando necessário. Nunca perca contexto novamente.