Lore

El grafo de conocimiento vivo para tu proyecto de software.

Estado: pre-1.0, mantenimiento individual. Lore es funcional y se utiliza en proyectos en producción, pero la API, el esquema y la superficie MCP aún pueden cambiar entre versiones menores. Los informes de errores son bienvenidos; es posible que las solicitudes de extracción (PR) de nuevas funcionalidades no se fusionen mientras el diseño se estabiliza. El repositorio se abrirá a una colaboración más amplia una vez que la API sea estable (objetivo: 1.0).

Lore captura la lógica de negocio de un proyecto —módulos, capacidades, flujos, eventos, reglas, formularios, entidades y decisiones— como un grafo tipado respaldado por SQLite, y lo expone a través de MCP para que los asistentes de codificación por IA (Claude Code, Cursor, Claude Desktop) puedan consultarlo y mantenerlo como parte del trabajo habitual.

Responde a preguntas como "¿cuántas formas existen de registrar un pago?", "¿qué se rompe si toco flow-checkout?" o "¿qué reglas protegen esta entidad?" en una sola llamada de herramienta, con procedencia y sin tener que volver a explorar el código base cada vez.

Por qué

• Memoria persistente entre sesiones: el grafo sobrevive a los reinicios de contexto.

• Cero sobrecarga de documentación: el asistente escribe a medida que se toman decisiones sobre los conceptos, no como una tarea separada.

• Auditable: cada nodo lleva source, confidence, source_context. Cada llamada MCP se registra.

• Eficiente en tokens: listados solo de resumen, operaciones por lotes, subagentes económicos para exploración, SQLite en modo WAL.

Related MCP server: kg-memory-mcp

Instalación (plugin de Claude Code — recomendado)

/plugin marketplace add YACB2/lore
/plugin install lore@lore

Recarga y, desde el proyecto que deseas modelar, ejecuta lore init (o /lore:bootstrap para una incorporación guiada que escanea el código con Haiku). Un "Proyecto" puede ser un único repositorio o un espacio de trabajo que contenga varios repositorios; Lore no tiene preferencias, .lore/lore.db se crea en relación con el directorio desde el que iniciaste Claude Code.

El plugin incluye:

• Servidor MCP que expone lore_add_node, lore_add_nodes, lore_update_node, lore_delete_node, lore_get_node, lore_add_edge, lore_add_edges, lore_remove_edge, lore_query, lore_traverse, lore_list, lore_find_variants, lore_audit, lore_history, lore_stats, lore_export_markdown.

• Habilidad invocada automáticamente (lore-usage) que le dice a Claude que lea antes de actuar y escriba al tomar una decisión, con reglas de procedencia y convenciones de ciclo de vida.

• Subagente lore-explorer (Haiku, solo lectura) para una exploración amplia sin consumir tokens costosos.

• Comandos de barra: /lore:init, /lore:bootstrap, /lore:audit, /lore:show <id>, /lore:recent, /lore:impact <id>, /lore:probe <path> (auditar el grafo de otro proyecto sin cambiar de directorio).

Instalación (CLI independiente / otros hosts MCP)

pipx install projectlore   # or: uv tool install projectlore
lore init

Para Cursor / Claude Desktop:

{
  "mcpServers": {
    "lore": {
      "command": "lore",
      "args": ["mcp", "--db", ".lore/lore.db"]
    }
  }
}

Referencia de CLI

lore init                      # create .lore/lore.db
lore list [--type flow]        # summary listing (id, type, title, status)
lore show <id>                 # full detail + edges
lore query "payment"           # exact id → title substring → tag fallback
lore variants <capability-id>  # flows implementing a capability
lore audit                     # orphans, cycles, id hygiene
lore stats [--since ISO]       # token/usage analytics from the audit log
lore export --out .lore/export # one markdown file per node

Esquema

Ocho tipos de nodos (independientes de la pila): module, capability, flow, event, rule, form, entity, decision.

Nueve relaciones: part_of, implements, depends_on, triggers, validates, enforces, supersedes, references, conflicts_with. Los pares de tipos están restringidos (ver schema.py).

Estados: active | draft | deprecated | superseded | archived. La eliminación lógica (soft-delete) es la predeterminada; lore_delete_node está reservado para errores tipográficos y advierte sobre la pérdida de aristas.

La abstracción central es capability (capacidad): algo que el sistema sabe hacer, independientemente de cómo. Múltiples nodos flow pueden implements la misma capacidad, revelando divergencias en la UX o la lógica.

Enrutamiento de modelos

Las operaciones se dividen según el costo:

• Lecturas (escaneos amplios, recorridos, auditorías): delegadas a Haiku a través del subagente lore-explorer o el frontmatter model: haiku en los comandos de barra.

• Escrituras y decisiones de modelado: modelo del llamador (Sonnet/Opus). Un subagente propone JSON; el llamador revisa y persiste.

Anulación por proyecto en .lore/config.json:

{
  "language": "es",
  "app_name": "my-app",
  "models": { "exploration": "haiku", "write": "sonnet" }
}

Procedencia e historial

Cada nodo lleva metadata.{source, confidence, source_context} y, cuando es relevante, source_ref (path:line), last_verified_at, deprecated_at, deprecated_reason, replaced_by.

lore_update_node(metadata_patch=…) fusiona sin destruir la procedencia; metadata sigue existiendo para reemplazos completos poco frecuentes.

lore_history(id) devuelve cada evento MCP para un nodo (el más reciente primero) desde el registro de auditoría de solo adición. lore_stats agrega por herramienta/operación e informa los bytes de entrada/salida.

Estado

Pre-MVP, alfa. El esquema y la superficie de herramientas MCP pueden cambiar antes de la versión 0.1.0.

Desarrollo

uv sync --all-groups
uv run pytest -q
uv run ruff check src tests

Las pruebas residen en tests/. El diseño del plugin es validado por test_plugin_structure.py.

Licencia

MIT.