Memory Graph

Un servidor del Protocolo de Contexto del Modelo (MCP) basado en grafos que proporciona memoria persistente a agentes de codificación de IA. Construido originalmente para Claude Code, MemoryGraph funciona con cualquier agente de codificación compatible con MCP. Almacena patrones de desarrollo, rastrea relaciones y recupera conocimiento contextual entre sesiones y proyectos.

GitHub

252

Documentación

MemoryGraph

CLI de memoria basada en grafos para agentes de codificación de IA

Un sistema de memoria basado en grafos que brinda a los agentes de codificación de IA memoria persistente.
Almacena patrones, rastrea relaciones y recupera conocimiento entre sesiones.

Uso con agentes de codificación

Los agentes de codificación ya ejecutan comandos de shell, por lo que pueden usar MemoryGraph directamente. Dos pasos: instalar globalmente y luego agregar instrucciones.

Instalación

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

memorygraph ahora está disponible desde cualquier directorio. Los datos persisten en ~/.memorygraph/.

Agregar instrucciones al agente

Pega esto en el archivo de instrucciones de tu agente (~/.claude/CLAUDE.md, .cursorrules, .windsurfrules o 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.

Sesión de ejemplo

# 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"

Configuración multiproyecto

Todos los proyectos comparten ~/.memorygraph/falkordblite.db de forma predeterminada. Para aislar por proyecto:

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

Solución de problemas

El agente no usa comandos: usa "REQUERIDO"/"DEBE" en las instrucciones, incluye comandos exactos
Comando no encontrado: bun link desde ts/, o asegúrate de que ~/.local/bin esté en PATH
Los recuerdos no persisten: memorygraph config para verificar la ruta, memorygraph health para verificar

¿Por qué MemoryGraph?

Las relaciones de grafo marcan la diferencia

El almacenamiento plano (CLAUDE.md, almacenes vectoriales) mantiene los recuerdos como entradas aisladas. El almacenamiento en grafo los conecta:

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

Consulta: "¿Qué pasó con la lógica de reintento?" devuelve la cadena causal completa, no solo recuerdos individuales.

Cuándo usar qué

Usa CLAUDE.md / AGENTS.md para	Usa MemoryGraph para
"Usa siempre sangría de 2 espacios"	"La última vez usamos 4 espacios y rompió el linter"
"Ejecuta las pruebas antes de confirmar"	"Las pruebas de autenticación fallaron por X, corregido con Y"
Reglas estáticas, directivas principales	Aprendizajes dinámicos con relaciones

Comandos CLI

Operaciones de memoria

Comando	Propósito	Ejemplo
`store`	Almacenar un nuevo recuerdo	`store --type solution --title "Fix" --content "..." --tags redis,fix`
`get`	Obtener un recuerdo por ID	`get <memory-id>`
`update`	Actualizar un recuerdo existente	`update <id> --title "New title"`
`delete`	Eliminar un recuerdo	`delete <memory-id>`
`search`	Buscar con filtros	`search --query "timeout" --tags redis --limit 10`
`recall`	Recuperación en lenguaje natural	`recall --query "authentication security"`
`related`	Obtener recuerdos relacionados	`related <id> --types SOLVES,CAUSES --max-depth 2`
`link`	Crear una relación	`link <from-id> <to-id> SOLVES --strength 0.8`

Búsqueda de contexto

Comando	Propósito
`context-search`	Buscar relaciones por tipo, fuerza o texto de contexto
`contextual-search`	Buscar dentro de los elementos relacionados de un recuerdo

Inteligencia

Comando	Propósito
`entities`	Extraer entidades (archivos, funciones, clases, tecnologías) de un recuerdo
`patterns`	Encontrar problemas similares y sugerir patrones
`context`	Obtener recuperación de contexto inteligente con coincidencia de entidades y palabras clave

Analítica

Comando	Propósito
`stats`	Estadísticas de la base de datos (cantidad de recuerdos, tipos, relaciones)
`activity`	Resumen de actividad reciente con problemas sin resolver
`visualize`	Datos de visualización de grafos (nodos y aristas)
`similarity`	Analizar similitud de soluciones para un recuerdo dado
`learning`	Recomendar rutas de aprendizaje para un tema
`gaps`	Identificar brechas de conocimiento (problemas sin resolver, conexiones faltantes)

Proactivo

Comando	Propósito
`briefing`	Generar un informe de sesión con actividad reciente y problemas abiertos
`predict`	Predecir lo que podría necesitarse según el contexto actual
`warn`	Advertir sobre problemas potenciales (enfoques obsoletos, errores conocidos)
`outcome`	Registrar un resultado para un recuerdo (seguimiento de éxito/fracaso)

Integración

Comando	Propósito
`capture`	Capturar el contexto de la tarea del entorno actual
`analyze-project`	Analizar el código base del proyecto actual
`workflow`	Rastrear o sugerir mejoras en el flujo de trabajo

Temporal

Comando	Propósito
`as-of`	Consultar relaciones tal como existían en un momento específico
`history`	Obtener el historial completo de relaciones de un recuerdo
`changes`	Mostrar cambios de relaciones desde una marca de tiempo

Gestión de datos

Comando	Propósito
`export`	Exportar a JSON o Markdown
`import`	Importar desde JSON
`migrate`	Migrar entre backends
`health`	Ejecutar una verificación de estado
`config`	Mostrar la configuración actual

Backends

Backend	Tipo	Configuración	Grafo nativo	Cero configuración	Mejor para
falkordblite (predeterminado)	Integrado	Ruta de archivo	Cypher	Sí	Predeterminado, consultas de grafo sin servidor
sqlite	Integrado	Ruta de archivo	Simulado	Sí	Respaldo sin dependencias
falkordb	Cliente-servidor	Host:puerto	Cypher	No	Producción de alto rendimiento
memgraph	Cliente-servidor	URI Bolt	Cypher	No	Analítica en tiempo real
cloud	Nube	Clave API	Cypher	No	Sincronización multidispositivo, uso compartido en equipo

Configuración del 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

Variables de entorno

Variable	Descripción	Predeterminado
`MEMORY_BACKEND`	Tipo de backend	`falkordblite`
`MEMORY_FALKORDBLITE_PATH`	Ruta de la base de datos FalkorDBLite	`~/.memorygraph/falkordblite.db`
`MEMORY_SQLITE_PATH`	Ruta de la base de datos SQLite	`~/.memorygraph/memory.db`
`MEMORY_FALKORDB_HOST`	Host del servidor FalkorDB	`localhost`
`MEMORY_FALKORDB_PORT`	Puerto del servidor FalkorDB	`6379`
`MEMORY_MEMGRAPH_URI`	URI Bolt de Memgraph	`bolt://localhost:7687`
`MEMORYGRAPH_API_KEY`	Clave API de la nube	-
`MEMORYGRAPH_API_URL`	URL de la API de la nube	`https://graph-api.memorygraph.dev`
`MEMORY_TOOL_PROFILE`	Perfil de herramientas (núcleo o extendido)	`core`
`MEMORY_LOG_LEVEL`	Nivel de registro	`INFO`

Tipos de memoria

Tipo	Caso de uso
`task`	Tareas y elementos de acción
`code_pattern`	Patrones de código recurrentes o convenciones
`problem`	Problemas o desafíos encontrados
`solution`	Soluciones, decisiones o enfoques elegidos
`project`	Contexto del proyecto, entorno, información de configuración
`technology`	Elecciones y evaluaciones de tecnología
`error`	Errores descubiertos
`fix`	Correcciones aplicadas a errores
`command`	Comandos útiles o fragmentos de CLI
`file_context`	Contexto sobre archivos específicos
`workflow`	Descripciones de flujos de trabajo o procesos
`general`	Recuerdos de propósito general
`conversation`	Resúmenes de conversaciones

Tipos de relación

Tipo	Significado
`RELATED_TO`	Conexión general
`BUILDS_ON`	Un recuerdo nuevo extiende uno más antiguo
`CONTRADICTS`	Un recuerdo nuevo reemplaza o invalida uno más antiguo
`CONFIRMS`	Un recuerdo nuevo proporciona evidencia para uno más antiguo
`SOLVES`	Una solución resuelve un problema
`CAUSES`	Un recuerdo causa otro
`REQUIRES`	Un recuerdo depende de otro
`IMPROVES`	Una mejora sobre un enfoque existente
`REPLACES`	Reemplaza un enfoque más antiguo
`DEPENDS_ON`	Dependencia de flujo de trabajo

Mejores prácticas de memoria

Flujo de trabajo de sesión

# 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

Agregar a CLAUDE.md o 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

Arquitectura

Estructura del proyecto

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

Compilación

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

Importación / Migración

# 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

El SDK de TypeScript proporciona un cliente para la API de MemoryGraph Cloud:

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"],
});

Licencia

Licencia MIT: consulta LICENSE.

Comienza simple. Mejora cuando sea necesario. Nunca pierdas el contexto de nuevo.