ContextKeep 🧠

Memoria a largo plazo infinita para agentes de IA

ContextKeep es un servidor de memoria potente e independiente que dota a tus agentes de IA (Claude, Cursor, Gemini, OpenCode y más) de un cerebro persistente y buscable. Deja de repetirte: permite que tu IA lo recuerde todo, permanentemente.

Características • Novedades en la V1.3 • Instalación • Herramientas MCP • Panel web • Configuración

🌟 Características

• ♾️ Contexto infinito: Almacena detalles de proyectos, preferencias, decisiones y fragmentos ilimitados; sin caducidad, sin límite de tamaño.

• 💰 Ahorra dinero y tokens: Extrae solo las memorias que importan, reduciendo drásticamente el uso de la ventana de contexto y los costes de API.

• 🔌 Compatibilidad universal: Funciona con cualquier cliente compatible con MCP a través de Stdio (local) o SSE (remoto/homelab).

• 🧭 Protocolo de índice de memoria: Un sistema de recuperación fiable de dos pasos — list_all_memories() → retrieve_memory() — para que los agentes siempre encuentren la clave correcta, cada vez.

• 🖥️ Panel web moderno: Gestiona tus memorias visualmente con vistas de cuadrícula, lista y calendario en una elegante interfaz oscura.

• 🔒 Privacidad primero: Almacenamiento 100% local. Tus datos nunca tocan un servidor externo.

• 🔎 Búsqueda inteligente: Búsqueda por palabras clave y semántica en todo el contenido de la memoria.

• 🐧 Servicio Linux: Se ejecuta silenciosamente en segundo plano como un servicio de systemd.

• 🐳 Listo para Docker: Despliegue con un solo comando mediante Docker Compose.

• ⬇️ Exportación y copia de seguridad: Exporta todas las memorias como JSON a través de la herramienta MCP o la interfaz web.

🆕 Novedades en la V1.3 — Harbor

🐳 Soporte para Docker

La petición número 1 de la comunidad. ContextKeep ahora incluye un Dockerfile y un docker-compose.yml para un despliegue con un solo comando:

docker compose up --build

Eso es todo. Servidor MCP en :5100, interfaz web en :5000, con almacenamiento persistente mediante volúmenes de Docker.

📦 Empaquetado moderno de Python

• pyproject.toml — especificación de dependencias canónica para uv, poetry o pip

• Soporte para uv — el instalador detecta automáticamente uv y utiliza uv sync para una configuración ultrarrápida

• Retrocompatible — pip install -r requirements.txt sigue funcionando

🛠️ 3 nuevas herramientas MCP (5 → 8 en total)

⬇️ Exportación desde la interfaz web

• Botón Exportar todo en la barra de herramientas (o pulsa Ctrl+E)

• Descarga un archivo contextkeep_backup_YYYY-MM-DD.json con marca de tiempo

🧹 Calidad del código

• Se ha corregido código muerto en memory_manager.py (un try/except duplicado inalcanzable)

• Se ha añadido el archivo core/__init__.py faltante para un empaquetado correcto en Python

• Se ha reemplazado except: genérico por except Exception: en todo el código

🚀 Instalación

Opción 1: Inicio rápido (pip)

1. Clona el repositorio:

git clone https://github.com/mordang7/ContextKeep.git
cd ContextKeep

2. Ejecuta el instalador:

   • Linux/macOS:

     python3 install.py

   • Windows:

     python install.py

3. Sigue el asistente: El instalador crea un entorno virtual, instala las dependencias y genera un archivo mcp_config.json listo para usar.

Opción 2: uv (Rápido)

git clone https://github.com/mordang7/ContextKeep.git
cd ContextKeep
uv sync
uv run python server.py

Opción 3: Docker (Recomendado para Homelabs)

git clone https://github.com/mordang7/ContextKeep.git
cd ContextKeep
docker compose up --build -d

Esto inicia:

Las memorias persisten en un volumen de Docker (contextkeep-data).

🛠️ Herramientas MCP

ContextKeep expone 8 herramientas MCP a cualquier agente conectado:

Directiva de agente recomendada

Añade esto a tu GEMINI.md, AGENTS.md o CLAUDE.md:

## Memory Index Protocol (MANDATORY)
1. FIRST — call `list_all_memories()` to get the complete key directory
2. THEN — call `retrieve_memory(exact_key)` using the exact key from step 1
Only use `search_memories()` for content-based searches, NOT for key lookup.

🔌 Configuración

Copia el contenido de mcp_config.example.json en el archivo de configuración de tu cliente de IA y actualiza las rutas.

Opción 1: Local (Claude Desktop / Gemini CLI / Cursor)

{
  "mcpServers": {
    "context-keep": {
      "command": "/absolute/path/to/ContextKeep/venv/bin/python",
      "args": ["/absolute/path/to/ContextKeep/server.py"]
    }
  }
}

Opción 2: Remoto vía SSH (Homelab / Raspberry Pi)

Ejecuta ContextKeep en un servidor doméstico y accede a él desde cualquier máquina de tu red:

{
  "mcpServers": {
    "context-keep": {
      "command": "ssh",
      "args": [
        "-i", "/path/to/private_key",
        "user@192.168.1.X",
        "'/path/to/ContextKeep/venv/bin/python'",
        "'/path/to/ContextKeep/server.py'"
      ]
    }
  }
}

Opción 3: Modo SSE (HTTP)

Ideal para OpenCode, aplicaciones web o cualquier cliente que prefiera el transporte HTTP:

{
  "mcpServers": {
    "context-keep": {
      "transport": "sse",
      "url": "http://localhost:5100/sse"
    }
  }
}

Opción 4: Docker

Usa mcp_config.docker.example.json o apunta tu cliente al contenedor:

{
  "mcpServers": {
    "context-keep": {
      "transport": "sse",
      "url": "http://localhost:5100/sse"
    }
  }
}

🌐 Panel web

ContextKeep incluye una interfaz web completa para gestionar tus memorias sin tocar la CLI.

• URL: http://localhost:5000

• Vista de cuadrícula: Tarjetas de memoria con etiquetas, recuentos de caracteres y acciones integradas

• Vista de lista: Tabla densa y escaneable con todas las memorias ordenadas por última actualización

• Vista de calendario: Explora tu historial de memoria por mes

• Búsqueda: Filtrado en tiempo real en títulos, claves y contenido

• CRUD completo: Crea, visualiza, edita y elimina memorias desde el navegador

• Exportación: Descarga todas las memorias como JSON con un solo clic (Ctrl+E)

Para iniciar manualmente:

./venv/bin/python webui.py

🐧 Configuración del servicio Linux (Recomendado para Homelabs)

Ejecuta tanto el servidor MCP como la interfaz web como servicios persistentes en segundo plano:

chmod +x install_services.sh
./install_services.sh

Esto instala:

Gestionar servicios:

sudo systemctl status contextkeep-server
sudo systemctl restart contextkeep-webui

📋 Registro de cambios

V1.3 — Harbor

• ✅ Soporte para Docker — Dockerfile + docker-compose.yml para despliegue con un solo comando

• ✅ Empaquetado moderno — pyproject.toml + soporte para uv junto a pip

• ✅ Nueva herramienta MCP: delete_memory() — los agentes ahora pueden eliminar memorias

• ✅ Nueva herramienta MCP: get_memory_stats() — recuento y tamaño de memoria de un vistazo

• ✅ Nueva herramienta MCP: export_memories() — copia de seguridad completa como JSON

• ✅ Interfaz web: Botón Exportar todo con atajo Ctrl+E

• ✅ Interfaz web: Endpoint de API de estadísticas

• ✅ Corrección: Código muerto eliminado en memory_manager.py

• ✅ Corrección: Se añadió core/__init__.py faltante para importaciones de Docker/paquetes

• ✅ Corrección: except genérico reemplazado por except Exception

• ✅ Instalador actualizado a V1.3 con detección de uv

• ✅ Colaboradores de la comunidad acreditados 🙏

V1.2 — Obsidian Lab

• ✅ Nueva herramienta MCP list_all_memories() — directorio de memoria completo en una sola llamada

• ✅ Rediseño de la interfaz Obsidian Lab — estética premium oscura con acentos cian/neón

• ✅ Insignia en vivo de recuento de memoria en el encabezado

• ✅ Navegación por mes en el calendario (adelante/atrás)

• ✅ Las tarjetas de cuadrícula ahora muestran etiquetas y distintivos de recuento de caracteres

• ✅ Barra lateral "Memorias recientes" eliminada para un diseño de calendario más limpio

• ✅ Protocolo de índice de memoria V1.2 — patrón de recuperación de agente de dos pasos estandarizado

V1.1

• Panel web con vistas de cuadrícula, lista y calendario

• Soporte de transporte SSE junto a Stdio

• Instalador de servicio systemd de Linux

• Títulos de memoria y marcas de tiempo

V1.0

• Servidor MCP central con store_memory, retrieve_memory, search_memories

• Almacenamiento persistente respaldado por JSON

• Soporte de transporte remoto SSH

🤝 Contribuciones

Las contribuciones son bienvenidas. Abre un PR, informa de un problema o sugiere una funcionalidad: toda aportación es apreciada.

Colaboradores de la comunidad en la V1.3

Un enorme agradecimiento a todos los que contribuyeron al lanzamiento de Harbor:

• @shuft — Abrió el Issue #1 solicitando soporte para Docker

• @Cyberdogs7 — PR #2: Implementación inicial de Docker y Docker Compose

• @frehov — PR #3: Dockerfile, pyproject.toml, soporte para uv, corrección de __init__.py

• @thinkstylestudio — Defensa de la comunidad

☕ Apoya el proyecto

Si ContextKeep te ahorra tiempo, tokens o salud mental, considera invitarme a un café.