GroundMemory

Identidad y memoria persistentes entre herramientas de IA - nativo de MCP, primero local, independiente del framework, listo para producción.

GitHub
3

Documentación

gm logo

GroundMemory

Identidad y memoria persistentes entre herramientas de IA: nativo de MCP, local primero, agnóstico de frameworks, listo para producción.

Python 3.12+ Release Unit Tests Test Suite License: MIT GitHub repo size GitHub language count GitHub top language

Inicio Rápido

Opción 1 - Docker (Recomendado)

git clone https://github.com/huss-mo/GroundMemory && cd GroundMemory
docker compose up -d
# -> listening on http://127.0.0.1:4242/mcp

Opción 2 - pip

pip install groundmemory && groundmemory-mcp
# -> listening on http://127.0.0.1:4242/mcp

Conecta tu cliente al servidor MCP

{
  "mcpServers": {
    "GroundMemory": {
      "url": "http://127.0.0.1:4242/mcp"
    }
  }
}

Puedes habilitar el acceso de red y reemplazar 127.0.0.1 con la IP LAN de tu servidor; consulta DOCS.md - Acceso de Red.
También puedes usar el servidor MCP a través del transporte stdio; consulta DOCS.md - Configuración del Cliente.

Tu agente ahora tiene memoria estructurada y buscable que persiste en cada sesión: hechos a largo plazo, un perfil de usuario, instrucciones del agente, un grafo de entidades y registros diarios, todo gestionado automáticamente. No se requieren cambios en el código de tu agente.

Esta configuración funciona con cualquier cliente compatible con MCP, incluidos asistentes de codificación con IA (Cursor, Cline, Windsurf, Claude Code, Codex CLI), clientes de escritorio con IA (Claude Desktop, Open WebUI) y frameworks y plataformas de agentes (LangChain, CrewAI, AutoGen, Google ADK, LiteLLM, n8n).

Para opciones de instalación, proveedores de embeddings, múltiples espacios de trabajo y la API de Python, consulta DOCS.md.

Lo Que Se Vuelve Posible

Sin memoria, cada sesión en cada herramienta de IA comienza desde cero. Con GroundMemory, los agentes pueden mantener continuidad a lo largo del tiempo, acumular conocimiento y comportarse como si realmente conocieran a la persona con la que trabajan. Hace que las conversaciones sean con estado, fluidas y naturales.

El intercambio a continuación es un ejemplo de cómo se ve esto. La primera sesión ocurre en Open WebUI. La segunda sesión ocurre en Cline (VS Code): una herramienta completamente diferente, sin historial compartido aparte del espacio de trabajo de GroundMemory al que ambas están conectadas.

Sesión 1 - Open WebUI (primera sesión)

Usuario

Hola

Agente

¡Hola! Bienvenido: este es el comienzo de algo bueno. Tengo memoria persistente, así que cualquier cosa de la que hablemos la llevaré conmigo a cada sesión futura. No necesitarás repetirte más adelante.

Un par de cosas rápidas para empezar:

  • ¿Cómo quieres que te llame?
  • ¿Hay algo que siempre quieras que tenga en cuenta: cómo te gusta trabajar, cosas a evitar, preferencias?

Sin prisa. Solo quiero conocerte.

Usuario

Soy Alice, ingeniera de backend que trabaja en un producto SaaS. Estamos construyendo una API de gestión de tareas: Node.js, PostgreSQL, Redis para caché, y planeamos usar BullMQ para colas de trabajos.

Agente

Entendido, Alice. Ingeniera de backend, API de gestión de tareas: Node.js, PostgreSQL, Redis, BullMQ para colas. Lo mantendré como base para todo lo que trabajemos juntos.

¿Algo más antes de sumergirnos? ¿O estás lista para empezar?

El agente escribe lo que aprendió en la memoria.

Sesión 2 - Cline en VS Code (herramienta diferente, mismo espacio de trabajo de GroundMemory)

Usuario

Oye. ¿Qué stack tecnológico acordamos usar para la API de gestión de tareas?

Agente

Estás construyendo una API de gestión de tareas con Node.js, PostgreSQL, Redis para caché y BullMQ para colas de trabajos. Eso es lo que decidimos.

Sin presentación. Sin configuración. El agente ya lo sabe.

Una identidad única en cada herramienta de IA que uses. Tu espacio de memoria no está vinculado a un solo asistente. Conecta Claude Desktop, Cursor, Cline y cualquier otra herramienta compatible con MCP al mismo servidor de GroundMemory y todas compartirán la misma memoria: tus preferencias, tu stack, tu trabajo en curso. Dejas de ser un extraño cada vez que abres una herramienta diferente. Hay algo genuinamente distinto en ser conocido en lugar de solo recibir respuestas: cambia la relación de transaccional a colaborativa y elimina el costo silencioso de restablecer el contexto que la mayoría no nota hasta que desaparece.

Un asistente de codificación/personal que construye un perfil con el tiempo. Después de algunas conversaciones, conoce tu horario, tus prioridades, cómo te gusta comunicarte, tu stack tecnológico, tus patrones preferidos y las decisiones arquitectónicas que ya has tomado. No necesita preguntar.

Un agente de investigación que construye un grafo de conocimiento. A medida que lee artículos y fuentes en muchas sesiones, registra entidades, relaciones y hallazgos.

Un agente orientado al cliente con memoria por usuario. En configuraciones multiusuario, cada usuario obtiene su propio espacio de trabajo: preferencias, historial, contexto en curso, lo que da a cada interacción un toque personalizado y con estado sin infraestructura personalizada.

Un agente autónomo de larga duración que sobrevive a los límites de contexto. Cada nueva sesión llama a memory_bootstrap para recargar los hechos persistidos, de modo que el agente retome exactamente donde terminó el anterior.

Copia de seguridad y restauración automáticas cuando la memoria crece. Cuando el contexto de memoria supera un umbral de tokens configurable, GroundMemory respalda automáticamente el espacio de trabajo en un archivo zip con marca de tiempo antes de pedir al agente que lo compacte. También puedes activar una copia de seguridad manualmente en cualquier momento con groundmemory --backup. Si algo sale mal, un solo comando restaura el estado anterior: groundmemory --restore -1.

Qué Hace GroundMemory

La mayoría de los agentes no tienen estado. Hacen las mismas preguntas una y otra vez, repiten los mismos errores y pierden el rastro de las preferencias del usuario y del trabajo en curso. Esto no es una limitación del modelo: es infraestructura faltante.

GroundMemory proporciona esa infraestructura. Da a tu agente una memoria estructurada y buscable que persiste entre sesiones, organizada en niveles distintos con propiedad clara:

ArchivoPropósito
MEMORY.mdHechos a largo plazo seleccionados: preferencias, decisiones, conocimiento persistente. Escrito por el agente usando memory_write(tier="long_term"). Sobrevive para siempre.
USER.mdPerfil de usuario estable: nombre, rol, estilo de trabajo. Editado manualmente o por el agente. Inyectado al inicio de cada sesión.
AGENTS.mdInstrucciones operativas del agente: cómo debe comportarse este agente, qué herramientas usar y cuándo. Inicializado con valores predeterminados sensatos.
RELATIONS.mdGrafo de relaciones de entidades: tripletas tipadas (Alice → works_at → Acme Corp). Escrito por memory_relate, espejo legible por humanos del grafo SQLite.
daily/YYYY-MM-DD.mdRegistros diarios de solo añadido: progreso de tareas, notas en curso, contexto de sesión. Escrito por memory_write(tier="daily").

Al inicio de la sesión, todos estos archivos se ensamblan en un bloque compacto de prompt del sistema que tu agente recibe como contexto, llamado inyección de arranque. En el momento de la búsqueda, todos los niveles se consultan juntos o individualmente.

Capacidades adicionales:

  • Búsqueda híbrida: la puntuación por palabras clave BM25 y la similitud coseno vectorial se combinan y reordenan en una sola consulta, de modo que la recuperación sea precisa incluso cuando la redacción difiere de lo almacenado.
  • Modo sin configuración: con provider: none, GroundMemory funciona completamente en SQLite con FTS5. Sin clave de API, sin GPU, sin dependencias adicionales.
  • Proveedores de embeddings conectables: cambia entre un modelo local de sentence-transformers, cualquier endpoint compatible con OpenAI (OpenAI, Ollama, LM Studio, LiteLLM) o solo BM25 sin tocar el código de tu agente.
  • Aislamiento de espacios de trabajo: cada proyecto, usuario o agente obtiene su propio espacio de trabajo respaldado por directorio con memoria, relaciones y registros diarios independientes.
  • Grafo de relaciones con deduplicación semántica: el grafo suprime automáticamente tripletas casi duplicadas usando un umbral de similitud coseno configurable.

Cómo Se Compara GroundMemory

La comparación refleja las funciones documentadas públicamente a partir de MAR-2026. Envía un PR si algo es inexacto.

FunciónGroundMemoryMem0LettamemsearchZep
Sin configuración (sin clave de API, sin GPU)✅----
Local primero / sin conexión✅--Parcial¹-
Memoria Markdown legible por humanos✅--✅-
Niveles de memoria estructurados✅✅²✅³--
Búsqueda híbrida BM25 + vectorial✅--✅✅
Grafo de relaciones de entidades✅✅--✅
Servidor nativo de MCP✅Parcial⁴Parcial⁵--
Grafo de conocimiento temporal-⁶---✅
Framework completo de agentes--✅--
Servicio en la nube gestionado-✅✅-✅

¹ memsearch admite embeddings ONNX locales + Milvus Lite, pero requiere descarga inicial del modelo
² Mem0 organiza la memoria en capas de Conversación, Sesión, Usuario y Organización
³ Letta usa bloques de Memoria Central (en contexto) + Memoria de Archivo (base de datos vectorial) + Búsqueda de Conversación
⁴ Mem0 ofrece una integración MCP, pero la interfaz principal es el SDK de Python/Node
⁵ Los agentes de Letta pueden consumir servidores MCP externos como herramientas; Letta en sí no es un servidor MCP
⁶ GroundMemory marca con marca de tiempo todas las relaciones, pero no admite consultas por rango de fechas.

Herramientas

En modo normal, GroundMemory expone cuatro herramientas: memory_bootstrap, memory_read, memory_write y memory_relate. Una herramienta opcional memory_list se puede habilitar mediante configuración. En modo despachador, todas las acciones se enrutan a través de una sola llamada memory_tool: útil para clientes que rinden mejor con menos herramientas en alcance.

Al usar el servidor MCP, indica a tu agente que llame a memory_bootstrap al inicio de cada sesión antes de hacer cualquier otra cosa, si descubres que no lo hace por defecto. Esto carga el contexto completo de memoria (MEMORY.md, USER.md, AGENTS.md, RELATIONS.md, registros diarios) en la conversación. Los clientes que admiten la primitiva de Prompts de MCP (Cline, Claude Desktop) pueden usar en su lugar el prompt memory_bootstrap_prompt desde su panel de Prompts.

Al usar la API de Python, llama a session.bootstrap() y pasa el resultado como tu prompt del sistema: no se necesita ninguna llamada de herramienta.

Para la referencia completa de herramientas, incluidos parámetros, niveles y filtros de fuente, consulta DOCS.md - Referencia de Herramientas.

Arquitectura

┌─────────────────────────────────────────────────────┐
│                    AI Agent / LLM                   │
│         (OpenAI, Anthropic, or any framework)       │
└────────────────────┬────────────────────────────────┘
                     │  tool calls + bootstrap prompt
                     ▼
┌─────────────────────────────────────────────────────┐
│                  MemorySession                      │
│   workspace  ·  index  ·  provider  ·  config       │
└───────┬──────────────┬──────────────────────────────┘
        │              │
        ▼              ▼
┌───────────┐  ┌───────────────────────────────────┐
│ Workspace │  │          MemoryIndex              │
│           │  │  SQLite + FTS5 (BM25 keyword)     │
│ MEMORY.md │  │  + optional vector store          │
│ USER.md   │  │  hybrid re-ranking + MMR          │
│ AGENTS.md │  └──────────────┬────────────────────┘
│ RELATIONS │                 │
│ daily/    │                 ▼
└───────────┘  ┌───────────────────────────────────┐
               │       EmbeddingProvider           │
               │  NullProvider  (BM25-only)        │
               │  SentenceTransformer  (local)     │
               │  OpenAICompatible  (HTTP API)     │
               └───────────────────────────────────┘

Para un desglose detallado de cada capa, el flujo de datos completo y el stack tecnológico, consulta DOCS.md - Arquitectura.

Contribuciones

Filosofía

GroundMemory está diseñado en torno a tres valores:

  1. Simplicidad sobre funciones. Cada adición debe justificar su complejidad. Un modo solo BM25 sin dependencias debe funcionar siempre.
  2. Sin conexión primero. La configuración predeterminada no debe requerir clave de API, conexión de red ni GPU.
  3. Impulsado por pruebas. El comportamiento nuevo se publica con pruebas. La suite completa debe pasar antes de fusionar cualquier PR.

Configuración de Desarrollo

git clone https://github.com/huss-mo/GroundMemory.git
cd GroundMemory

# Install with all dev dependencies
pip install -e ".[dev,local]"

# Or with uv
uv sync --extra dev --extra local

Ejecutar la Suite de Pruebas

# Core tests - no extra deps or config required (fast, always passes)
pytest

# Local model tests - sentence-transformers + cross-encoder
# Requires: pip install groundmemory[local]
pytest -m local

# API embedding tests - OpenAI-compatible HTTP endpoint
# Requires: endpoint configured via .env (see below)
pytest -m api_embeddings

# All marked tests together
pytest -m "local or api_embeddings"

# With coverage
pytest --cov=groundmemory --cov-report=term-missing

Pruebas local descargan modelos reales de sentence-transformers y cross-encoder en la primera ejecución. Los nombres de los modelos se leen de la configuración (embedding.local_model, search.rerank_model). Se omiten automáticamente cuando sentence-transformers no está instalado.

Pruebas api_embeddings requieren un endpoint de embeddings compatible con OpenAI configurado. Toda la configuración se lee de .env (raíz del proyecto o ~/.groundmemory/). Las pruebas se omiten automáticamente cuando embedding.provider no es openai o el endpoint no es accesible.

.env mínimo para api_embeddings:

GROUNDMEMORY_EMBEDDING__PROVIDER=openai
GROUNDMEMORY_EMBEDDING__BASE_URL=http://localhost:11434/v1
GROUNDMEMORY_EMBEDDING__API_KEY=ollama
GROUNDMEMORY_EMBEDDING__MODEL=nomic-embed-text

Cualquier endpoint compatible con OpenAI funciona: OpenAI, Ollama, LM Studio, LiteLLM, etc. Ejecutar pytest sin la bandera -m ejecuta todo: las pruebas marcadas se omiten con elegancia cuando no se cumplen sus requisitos.

Enviar un PR

  1. Haz un fork del repositorio y crea una rama: git checkout -b feature/your-feature-name
  2. Haz tus cambios con pruebas adjuntas.
  3. Ejecuta las pruebas: todas las pruebas unitarias deben pasar.
  4. Abre una solicitud de extracción con una descripción clara de qué cambia y por qué.

Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulta el archivo LICENSE para más detalles.