Lorekeeper

Lorekeeper

Memoria auto-mejorada para agentes de IA. Un comando, sin nube, sin configuración.

pip install lorekeeper-mcp && lorekeeper setup && lorekeeper

Tu agente recuerda entre sesiones — y la memoria mejora en calidad, no solo en tamaño. Local. Sin claves de API. Sin registro. Gratis para ejecutar para siempre.

---

Por qué Lorekeeper

Cada sesión de agente de IA comienza en blanco. Reexplicas el contexto, reafirmas preferencias, reenseñas patrones — cada vez.

Archivos como CLAUDE.md y .cursorrules ayudan, pero se mantienen a mano, no pueden buscarse a sí mismos y se vuelven obsoletos. Los servicios en la nube funcionan, pero los datos de tu sesión salen de tu máquina y pagas por cada llamada de API. Las bibliotecas son potentes, pero escribes la integración tú mismo.

Lorekeeper tiene una forma diferente: un servidor MCP local que instalas pip install una vez. Se conecta a tus agentes existentes, almacena memorias en SQLite en tu propio disco y comienza a mejorar con cada sesión:

Agent uses a memory → rates it useful or not →
scores adjust automatically → weak memories decay →
strong memories surface more often → search gets sharper

Una instalación nueva y una de seis meses son productos genuinamente diferentes. Cuanto más lo usas, menos ruido obtienes — y más sientes que tus agentes realmente conocen tu código.

---

Inicio Rápido

3 minutos, cero configuración:

# 1. Install
pip install lorekeeper-mcp

# 2. Configure your agents (auto-detects Hermes, Claude Code, Cursor)
lorekeeper setup

# 3. Start the MCP server
lorekeeper

lorekeeper setup escanea los agentes instalados e inyecta la entrada MCP, el prompt del agente y las habilidades incluidas automáticamente. Usa --check para previsualizar sin escribir. Ejecuta lorekeeper --help o lorekeeper --version para verificar la instalación.

Luego pregúntale a tu agente:

"Recuerda que prefiero curl -vX GET para depurar endpoints."

Llama a lore_remember → memoria almacenada. Siguiente sesión:

"¿Cuál es mi comando de depuración preferido?"

Llama a lore_search → memoria recuperada. ✅

Guía completa → docs/quickstart.md

---

Características

Qué	Cómo
Búsqueda híbrida	Vectores semánticos + palabras clave BM25 + decaimiento temporal + frecuencia de uso + puntuación de memoria — todo clasificado por una fórmula ponderada
Auto-mejora	La retroalimentación de lore_update ajusta las puntuaciones. Las malas memorias se desvanecen (<2 confianza + no útil → borrado suave). Las buenas suben.
Auto-enlace	Las nuevas memorias se enlazan automáticamente a su vecino semántico más cercano. Se forma un grafo de conocimiento ligero sin esfuerzo.
Detección de duplicados	Las nuevas inserciones se verifican contra las memorias existentes. El contenido casi idéntico se bloquea (anular con force=true).
Panel de control	Interfaz web completa — navegar, buscar, editar, eliminar. Siete pestañas incluyendo copia de seguridad/restauración con vista previa de deduplicación.
MCP universal	Funciona con Claude Code, Cursor, Hermes, Copilot, OpenCode — cualquier agente compatible con MCP.
Local primero	Tus datos permanecen en tu máquina. SQLite + LanceDB. Sin dependencia de nube, sin claves de API.
Espacios de nombres	Múltiples agentes comparten un almacén con espacios de nombres aislados. Las escrituras van a tu espacio; las lecturas incluyen el grupo compartido.
Reflexión	Los agentes extraen aprendizajes automáticamente de las sesiones. Los descubrimientos y lecciones se convierten en memorias buscables.

---

Casos de Uso

Mantenerse en contexto entre sesiones

Configuras tu capa de autenticación el lunes. El miércoles, un agente diferente comienza desde cero sin idea. Con Lorekeeper, ya conoce la ruta del middleware, el formato del token y qué prueba cubre el caso límite — porque se lo dijiste una vez.

"Remember that our JWT uses jose middleware in src/middleware/auth.ts
 and refresh tokens expire in 7 days."
→ lore_remember stores it
→ Every future session, on any agent: already in context

Un grupo de memoria, múltiples agentes

Claude Code para revisión, Cursor para implementación, Hermes para planificación — no deberían empezar desde cero cada uno. Los espacios de nombres de Lorekeeper les permiten compartir un almacén. El descubrimiento de un agente se convierte en conocimiento de todos los agentes.

→ Engineer agent notes a performance quirk in the search service
→ lore_remember stores it under the shared namespace
→ PM agent surfaces it during sprint planning
→ No briefing, no copy-paste

Depuración entre sesiones

Arreglaste un sutil error de CORS hace tres semanas y tu agente ayudó. Ninguno de los dos recuerda los detalles.

"What did we figure out about the CORS issue?"
→ lore_search returns the root cause, the fix, and the context around it

Incorporación de proyectos

Nuevo repositorio, nueva sesión de agente. En lugar de reexplicar la arquitectura, ejecutas unas pocas llamadas a lore_remember después de la primera sesión. La siguiente sesión — y cada agente después — comienza con la base correcta.

"Remember: the payment service requires X-Idempotency-Key on all POST requests."
→ Claude Code, Cursor, and Codex all read from the same store

---

Para Quién Es

Para ti, si usas:

• Claude Code y quieres que recuerde el contexto del proyecto entre sesiones
• Cursor y quieres memoria persistente del agente
• Hermes, OpenCode, Codex CLI, Copilot CLI, o cualquier agente compatible con MCP
• Múltiples agentes y quieres que compartan conocimiento

No para ti todavía, si:

• Necesitas RBAC de equipo, registros de auditoría o SSO (próximamente después de la beta)
• Estás construyendo una aplicación de IA para consumidores (somos primero para agentes, no primero para API)
• No usas agentes de codificación con IA (Lorekeeper es una herramienta MCP)

---

Cómo Se Compara

Hay grandes herramientas en este espacio — cada una hace diferentes concesiones. Aquí es donde se sitúa Lorekeeper:

	Basado en archivos	Servicios en la nube	Servidores Docker	Biblioteca (Mem0)	agentmemory (Node)	Lorekeeper
Configuración	Integrado	Clave de API + configuración en la nube	docker compose	Escribir código de integración	npx agentmemory	pip install
Datos	Local	Nube	Local	Tú decides	Local	Local
Búsqueda	grep	Vector	Vector	Vector	Híbrida	Híbrida + decaimiento temporal + uso + puntuación
Auto-mejora	❌	❌	❌	❌	❌	✅ Bucle de calidad
Grafo de conocimiento	❌	De pago	❌	De pago	❌	✅ Auto-enlace gratuito
Panel de control	❌	✅	❌	❌	Visor	✅ Interfaz web completa
Dependencias	Ninguna	~300MB	~2GB	~1.4GB	~200MB	~1.4GB (embeddings)
Construido por agentes	❌	❌	❌	❌	❌	✅ Usado a diario

Los servicios en la nube y las soluciones basadas en Docker son opciones sólidas para equipos o aplicaciones de producción. Lorekeeper está optimizado para el otro extremo: desarrolladores individuales y flujos de trabajo de agentes donde cero operaciones, cero nube y un almacén auto-mejorable importan más.

Nota sobre dependencias: ~1.4GB proviene del modelo de embeddings sentence-transformers (PyTorch). Esto es la misma clase de peso que cualquier solución de embeddings local. Somos honestos al respecto.

---

Herramientas MCP

Lorekeeper expone 10 herramientas MCP que cubren el ciclo de vida completo de la memoria:

Herramienta	Propósito
lore_search	Búsqueda híbrida semántica + palabras clave con puntuaciones de relevancia
lore_remember	Guardado rápido de memoria en un solo paso (títulos automáticos, enlaces automáticos)
lore_insert	Inserción estructurada por lotes con puntuaciones y enlaces personalizados
lore_update	Bucle de retroalimentación — califica memorias, impulsa la calidad
lore_forget	Borrado suave de memorias incorrectas u obsoletas
lore_reflect	Fin de sesión: extrae aprendizajes, guarda descubrimientos automáticamente
lore_processed_sessions	Verifica qué sesiones ya están procesadas
lore_recommend_links	Sugiere enlaces candidatos entre memorias relacionadas
lore_get_suggestions	Lista sugerencias de enlaces pendientes del motor de barrido
lore_review_suggestion	Acepta o rechaza una o más sugerencias de enlaces (por lotes)

Referencia completa de API → docs/api-reference.md

---

Panel de Control

Una interfaz web local para navegar, buscar, editar y gestionar tu almacén de memoria.

lorekeeper-dashboard
# → http://127.0.0.1:7777

Siete pestañas:

Pestaña	Qué hace
Memorias	Tabla ordenable con filtro en vivo — título, puntuación, confianza, uso, fechas
Detalle	Edita el contenido de una memoria, gestiona sus enlaces, borrado suave o borrado definitivo
Enlaces	Navega el grafo de conocimiento — fuente → relación → destino
Consulta	Búsquedas semánticas + de palabras clave ad hoc con desglose de puntuación por resultado
Sesiones	Todas las sesiones de agentes procesadas con aprendizajes extraídos
Configuración	Ajuste en vivo de pesos de búsqueda, umbrales de calidad, límites
Copia de seguridad	Exportar/importar memorias como JSON con vista previa de deduplicación
Sugerencias	Revisa candidatos de enlaces generados por IA del motor de barrido — acepta o rechaza uno por uno o en lote

Pestaña de Sugerencias

La pestaña de Sugerencias muestra candidatos de enlaces generados automáticamente por el motor de barrido en segundo plano. Cada candidato es un par de memorias que el motor considera relacionadas, puntuado por similitud de coseno, superposición de palabras clave BM25, co-ocurrencia de entidades y proximidad temporal.

Flujo de trabajo:

1. El motor de barrido se ejecuta en un intervalo configurable (LORE_SUGGEST_INTERVAL_HOURS, por defecto 12).
2. Los candidatos aparecen en la pestaña de Sugerencias, ordenados por puntuación (mayor primero).
3. Haz clic en ✓ (o selecciona varias filas + Aceptar Seleccionadas) para crear un enlace permanente entre las dos memorias.
4. Haz clic en ✗ (o Rechazar Seleccionadas) para descartar — los pares rechazados nunca se vuelven a mostrar en futuros barridos.
5. Usa Ejecutar Barrido en la pestaña de Configuración para ejecutar el barrido inmediatamente en lugar de esperar el intervalo.

Configuración del barrido (a través de variables de entorno con prefijo LORE_ o la pestaña de Configuración):

Configuración	Por defecto	Descripción
LORE_SUGGEST_INTERVAL_HOURS	12	Con qué frecuencia se ejecuta el barrido (horas)
LORE_SUGGEST_MIN_SCORE	0.55	Puntuación ponderada mínima para mostrar un candidato
LORE_SUGGEST_MAX_CANDIDATES	500	Máximo de candidatos por ejecución de barrido
LORE_SUGGEST_TTL_DAYS	30	Días antes de que las sugerencias no revisadas se eliminen

---

Construido por Agentes, Para Agentes

Lorekeeper se desarrolla usando agentes de IA — Claude Code, Hermes y nuestro propio equipo de agentes. El ciclo de desarrollo es en sí mismo una demostración funcional de lo que hace:

agent builds a feature → uses Lorekeeper to capture what it learned →
searches those memories next session →
builds the next feature with the context already there

Esto no es una línea de marketing. Cada esquema de herramienta, tipo de retorno y flujo de trabajo en Lorekeeper fue moldeado por agentes que lo usan a diario — no por humanos leyendo especificaciones. Cuando algo era molesto de usar, lo cambiábamos. Cuando la búsqueda devolvía ruido, ajustábamos los pesos. El producto es lo que es porque los agentes que lo construyen dependen de él.

El bucle de desarrollo agéntico documentado en este repositorio es cómo trabajamos realmente — y es lo que Lorekeeper está diseñado para apoyarte.

---

Para Desarrolladores

Clona, ejecuta desde el código fuente o contribuye:

git clone https://github.com/Jessinra/Lorekeeper.git
cd Lorekeeper
bash scripts/setup.sh

# Tests
uv run pytest

# Lint
uv run ruff check src tests

# Type check
uv run mypy src

# Dashboard dev
uv sync --extra dashboard
uv run lorekeeper-dashboard

Estructura del Proyecto

src/lorekeeper/
├── __main__.py          # Entrypoint — init_service() + mcp.run(stdio)
├── server.py            # FastMCP tool definitions (8 tools)
├── config.py            # Settings (pydantic-settings, LORE_ prefix)
├── models.py            # Pydantic models
├── dashboard/           # Web UI (FastAPI + uvicorn)
└── services/
    ├── orchestrator.py  # MemoryService — coordinates sub-services
    ├── memory_engine.py # Vector store abstraction
    ├── lancedb_engine.py# LanceDB backend
    ├── link_store.py    # SQLite — memories, links, suggestions
    ├── keyword_index.py # BM25 index
    ├── search.py        # Hybrid ranking
    └── ...

Configuración Clave

Todos los ajustes mediante variables de entorno con prefijo LORE_ o la pestaña Config del panel:

Variable	Predeterminado	Descripción
LORE_DATA_DIR	~/.lorekeeper	Directorio de datos (SQLite + vectores)
LORE_NAMESPACE	shared	Espacio de nombres del agente — escrituras limitadas, lecturas unidas con shared
LORE_SEARCH_LIMIT	5	Número de resultados predeterminado de lore_search
LORE_LINK_TOP_M	10	Máximo de candidatos devueltos por lore_recommend_links
LORE_LINK_SCORE_THRESHOLD	0.3	Puntuación mínima para que los candidatos de enlace aparezcan
LORE_LINK_TEMPORAL_TAU_DAYS	30	Vida media de decaimiento para la puntuación de proximidad temporal (días)

Lista completa → src/lorekeeper/config.py y CLAUDE.md.

---

Rendimiento

Todas las 500 preguntas de LongMemEval-S, pesos híbridos predeterminados (sem=0.45, kw=0.30):

Métrica	Valor	Latencia
R@1	84.6%	32.9 ms/consulta
R@3	93.6%
R@5	96.6%
R@10	98.8%

Desglose completo por categoría → docs/research/2026-06-11-retrieval-benchmark-results.md

---

Licencia

Apache-2.0 — consulta LICENSE.

---

Construido por agentes, para agentes. Manifiesto · Estrategia

Última verificación: 2026-06-20