📜 Litopys

Una crónica viva para tu IA.

Memoria persistente basada en grafos que sobrevive a través de sesiones y clientes. Creada para Claude Code, Claude Desktop y cualquier agente compatible con MCP.

litopys-dev.github.io/litopys — instalación, capturas de pantalla y guía de inicio rápido

🇺🇦 Читати українською

¿Por qué Litopys?

Los sistemas de memoria para agentes de IA actuales fuerzan un compromiso: o bases de datos vectoriales pesadas con fugas de subprocesos y un consumo de ~500 MB de RAM, o archivos markdown planos que no escalan más allá de unas pocas docenas de notas.

Litopys toma un tercer camino: un grafo tipado de conocimiento almacenado en markdown plano, servido a través de una capa MCP ligera (~75 MB de RAM), editable a mano y consultable tanto por palabras clave como por estructura. Litopys significa "crónica" en ucraniano, porque eso es exactamente lo que debería ser la memoria de tu IA: un registro vivo de lo que aprendió sobre ti, cuándo y por qué.

Related MCP server: auxly-memory-cli

Características

• 🧠 Grafo tipado — 6 tipos de nodos (persona, proyecto, sistema, concepto, evento, lección) con 11 relaciones de primera clase

• 🔌 Nativo de MCP — funciona con Claude Code, Claude Desktop, Cursor, Cline o cualquier cliente MCP (ver docs/integrations)

• 📝 Primero Markdown — cada nodo es un archivo .md plano con frontmatter YAML. Editable a mano, buscable con grep, versionado con git

• 🤖 Extractor agnóstico al modelo — Anthropic, OpenAI o Ollama local. Elige según tu presupuesto de recursos/costes (ver Huella de recursos más abajo). Los hechos pasan por una cuarentena para que nada se guarde sin revisar

• 🌐 Panel web — navega, busca, edita, visualiza el grafo y revisa la cuarentena en http://localhost:3999

• 🔐 Permanece local — el grafo vive en ~/.litopys/graph/ como archivos; el servidor se vincula a 127.0.0.1 por defecto; sin telemetría

Panel de control

Capturas de pantalla tomadas con un grafo de demostración sintético incluido en docs/screenshots/ — no son las notas personales del autor.

Estado

v0.1.2 ya está disponible — binarios precompilados para Linux / macOS / Windows (x64 + arm64), con sumas de verificación SHA-256 verificadas por install.sh. Lanzamiento de seguridad sobre la línea estable v0.1.1 — consulta el CHANGELOG. Las superficies públicas (herramientas MCP, CLI, exportación JSON schemaVersion: 1, diseño de markdown en disco) están congeladas; los cambios disruptivos se enviarán como 0.2.x.

Grafo central, servidor MCP (5 herramientas, stdio + HTTP/SSE), extractor + cuarentena + resumen semanal, demonio de temporizador, panel de control (lectura + escritura + visualización de grafo + revisión de cuarentena), barreras de resolución de identidad, compilación de binario único, instalador de una línea, documentación de integración por cliente — todo enviado. Consulta Qué sigue para los planes futuros.

Huella de recursos

Números honestos de la propia instalación del autor (Ubuntu, Bun 1.x). El servidor MCP es barato; el extractor es donde se ve el coste, y depende de qué adaptador elijas.

Por lo tanto, el coste residente mínimo es de ~75 MB para el servidor MCP. La extracción es opcional: puedes ejecutar Litopys solo de lectura/escritura desde tu agente y nunca iniciar el demonio. Si habilitas la extracción, la ruta de Ollama local cambia dinero por RAM; la ruta de Anthropic/OpenAI cambia RAM por centavos por sesión. El keep_alive de Ollama significa que las cifras de 3B/7B son transitorias: el modelo sale de la RAM unos minutos después de que termine el tick.

Inicio rápido

Instalación de una línea (Linux / macOS):

curl -fsSL https://raw.githubusercontent.com/litopys-dev/litopys/main/install.sh | sh

Esto descarga un único binario de ~100 MB a ~/.local/bin/litopys, inicializa ~/.litopys/graph/ con los subdirectorios requeridos e imprime sugerencias de registro de MCP.

Fija una versión específica colocando la asignación después de la tubería — las variables de entorno establecidas antes de curl solo tienen alcance para el propio curl, no para el shell canalizado:

curl -fsSL https://raw.githubusercontent.com/litopys-dev/litopys/main/install.sh | LITOPYS_VERSION=v0.1.2 sh

Luego registra el servidor MCP con tu cliente:

# Claude Code
claude mcp add litopys -- ~/.local/bin/litopys mcp stdio

// Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "litopys": {
      "command": "/home/you/.local/bin/litopys",
      "args": ["mcp", "stdio"]
    }
  }
}

Reinicia el cliente. El recurso litopys://startup-context carga automáticamente el perfil del propietario, proyectos activos, eventos recientes y lecciones clave en cada sesión nueva. El agente lee/escribe a través de cinco herramientas MCP: litopys_search, litopys_get, litopys_related, litopys_create, litopys_link.

Las recetas completas específicas para cada cliente se encuentran en docs/integrations/ — Claude Code, Claude Desktop, Cursor, Cline, conectores de ChatGPT, Gemini.

Modo remoto (HTTP/SSE)

Para clientes remotos (conectores de Claude Desktop, hosts MCP basados en navegador):

LITOPYS_MCP_TOKEN=your-secret litopys mcp http
# listens on 127.0.0.1:7777 by default
# set LITOPYS_MCP_BIND_ADDR=0.0.0.0 + TLS proxy for remote exposure
# set LITOPYS_MCP_CORS_ORIGIN=https://your-client to enable CORS

Instalación de desarrollo (desde el código fuente)

git clone https://github.com/litopys-dev/litopys.git
cd litopys
bun install
bun run build:binary       # produces dist/litopys

Opcional — demonio para transcripciones de larga duración

cp packages/daemon/systemd/litopys-daemon.{service,timer} ~/.config/systemd/user/
systemctl --user enable --now litopys-daemon.timer

Opcional — inicio automático del panel web

El panel de control (litopys viewer) puede ejecutarse como un servicio de usuario de systemd para que vuelva después de cada reinicio.

litopys viewer install        # generates token, writes unit, enables service
litopys viewer install --lan  # same + binds to 0.0.0.0 for LAN access
systemctl --user status litopys-viewer

# Remove:
litopys viewer uninstall

Token de acceso. viewer install genera un token aleatorio automáticamente y lo guarda en ~/.litopys/viewer.token. La salida de la instalación imprime una URL lista para usar con el token incrustado:

✓ litopys-viewer installed

  Open dashboard:    http://localhost:3999/?token=<token>
  Share with others: http://192.168.1.x:3999/?token=<token>   # --lan only

  Opening the link once saves the token — no re-entry needed.
  Retrieve token later: cat ~/.litopys/viewer.token

Abrir la URL una vez guarda el token en localStorage — no hay más avisos. Para compartir el acceso de escritura con alguien, envíale la URL que incluye ?token=…. Para recuperar el token en cualquier momento: cat ~/.litopys/viewer.token.

Los endpoints GET (navegar, buscar, vista de grafo) están siempre abiertos. Los endpoints de mutación (crear / editar / eliminar nodos, aceptar o rechazar cuarentena) requieren el token.

O establece LITOPYS_ENABLE_VIEWER=1 al ejecutar install.sh para habilitarlo como parte de la instalación de una línea. Requiere loginctl enable-linger $USER si quieres que el panel de control permanezca activo después de cerrar sesión.

Verificación de integridad

litopys check           # human-readable report, grouped by error kind
litopys check --json    # { nodeCount, edgeCount, errorCount, errors[] } for CI

Carga y resuelve todo el grafo, luego marca referencias rotas, IDs duplicados, relaciones de tipo incorrecto y fallos de análisis/validación. Sale con un código distinto de cero cuando se encuentran problemas — inclúyelo en un hook de pre-push de git o paso de CI para que la desviación nunca se produzca silenciosamente.

Copia de seguridad de tu grafo

Litopys almacena todo como markdown plano en ~/.litopys/graph/, por lo que cualquier herramienta que versiona archivos funciona. Dos enfoques comunes:

Git + remoto privado (historial incremental, externo, gratuito):

cd ~/.litopys
git init
git add graph/ .gitignore README.md
git commit -m "baseline"
gh repo create my-litopys-graph --private --source=. --push

A partir de ahí, cada hook de fin de sesión o aceptación manual deja tu árbol de trabajo sucio — periódicamente haz git add -A && git commit -m "sync" && git push para mantener la copia de seguridad actualizada. Tu grafo contiene hechos personales, así que mantén el remoto privado.

Instantánea JSON (portable, diferenciable, amigable con herramientas):

litopys export > graph.json              # compact
litopys export --pretty > graph.json     # indented, VCS-friendly
litopys export --no-body > meta.json     # metadata only, strip markdown bodies

El volcado lleva meta (exportedAt, counts, schemaVersion) más todos los nodos ordenados por ID y aristas ordenadas por (from, relation, to) — determinista entre ejecuciones, por lo que diff graph-yesterday.json graph-today.json te dice exactamente lo que el LLM/demonio añadió. Aliméntalo a herramientas de análisis, migra entre hosts o confirma junto con el código.

Restaurar desde una instantánea en un host nuevo (o después de una reinstalación):

litopys import graph.json --dry-run   # preview the plan
litopys import graph.json             # create new nodes, skip existing ones
litopys import graph.json --force     # also overwrite existing ids

El valor predeterminado es conservador: los nodos existentes nunca se tocan a menos que pases --force. Cada nodo se valida contra el esquema por adelantado, por lo que una instantánea corrupta se aborta antes de que nada llegue al disco.

Historial de versiones

Consulta CHANGELOG.md. El trabajo futuro está impulsado por los comentarios de los usuarios reales — abre un issue si algo molesta.

Principios de diseño

• Agnóstico al agente. Sin dependencia estricta de ningún proveedor de LLM o cliente. MCP es el único punto de integración. Ollama es el extractor predeterminado; Anthropic/OpenAI son adaptadores opcionales.

• Datos portables. El grafo es markdown plano + frontmatter YAML en disco. Legible en cualquier editor, versionable en git, buscable desde el shell.

• Runtime ligero. ~75 MB de RAM para el servidor MCP. El extractor está fuera de proceso y se ejecuta según tu programación, no en cada solicitud — consulta Huella de recursos para el desglose completo de costes entre adaptadores.

• Integraciones opcionales. Los ayudantes específicos del cliente (hooks, fragmentos de configuración) viven en docs/integrations/ — puedes usar Litopys sin ninguno de ellos.

Licencia

MIT © 2026 Denis Blashchytsia y colaboradores de Litopys.