Chronica

Servidor MCP de memoria persistente para Claude Desktop — recuerda contexto, tiempo y temas a través de sesiones

Documentación

Chronica 🗝️

Una capa de memoria persistente para Claude Desktop mediante MCP
Un servidor MCP que otorga memoria a largo plazo a Claude Desktop

"Las conversaciones con IA lo olvidan todo cuando termina la sesión.
Chronica lo recuerda — para que Claude pueda continuar justo donde lo dejaste."

¿Qué es Chronica?

Chronica es un servidor de Protocolo de Contexto de Modelo (MCP) que le otorga a Claude Desktop memoria persistente y estructurada entre sesiones.

Cuando inicias una nueva conversación, Claude llama a chronica_compose_opening con el nombre del proyecto actual — y te saluda con conocimiento de:

✅ La hora actual (zona horaria local del PC, detectada automáticamente)
✅ Hasta cinco entradas de memoria recientes limitadas al proyecto (vista previa del título, tipo, antigüedad — no el texto completo)
✅ Elementos abiertos de pregunta / acción de ese segmento, señalados para seguimiento

Cada turno del usuario también puede sincronizar JSON ligero de tiempo/antigüedad mediante chronica_session_tick. Sin el argumento project en compose_opening, las memorias de otros proyectos pueden mezclarse — las descripciones de las herramientas requieren pasarlo siempre (o confirmar el nombre con list_threads primero).

Nunca más "no tengo contexto de sesiones anteriores". Chronica resuelve esto a nivel de arquitectura.

¿Qué es Chronica?

Chronica es un servidor MCP que le otorga a Claude Desktop memoria a través de conversaciones.

Las conversaciones con IA se reinician por completo cuando termina la sesión.
Con Chronica, Claude carga un resumen de memoria con nombre de proyecto al inicio de la conversación mediante chronica_compose_opening, y puede continuar naturalmente desde donde quedó (los detalles se obtienen según sea necesario con chronica_search y otras herramientas).

Características / Funciones

Herramienta	Descripción
`compose_opening`	Genera un texto de resumen al inicio de la conversación con la hora actual, las 5 entradas más recientes del `project` especificado y elementos pendientes (pregunta/acción). Se asume que `project` es obligatorio (para evitar mezclas)
`session_tick`	JSON ligero para cada turno (hora actual, "hace cuántos días", temas recientes). Como MCP no puede hacer push, se recomienda llamarlo en cada turno
`save_entry`	Claude guarda automáticamente el contenido de la conversación (notas, decisiones, tareas, etc. — 5 tipos)
`search`	Busca memorias por etiquetas, tipo y hilo
`timeline`	Obtiene una línea de tiempo con rango de fechas especificado
`summarize`	Genera resúmenes diarios, semanales y de decisiones
`get_last_seen`	Obtiene la hora de la última conversación
`create_thread`	Crea un hilo (tema de conversación)
`list_threads`	Obtiene la lista de hilos
`get_thread_info`	Obtiene información detallada de un hilo

Interfaz de Curación (pantalla de curación)

Una interfaz de administración creada con Streamlit para organizar las memorias acumuladas.

📋 Visualización de lista de memorias (filtro por tipo y etiqueta)
🗑️ Eliminación de memorias innecesarias (sin edición, solo eliminación)
📊 Visualización del uso de tokens (TOP 10, tasa de uso)

📸 Capturas de pantalla

Interfaz de Curación — Panel de administración de memorias

Curation UI

Claude Desktop — Invocación automática de herramientas

Claude Desktop Tools

Claude Desktop — Memoria guardada y respuesta personalizada

Claude Desktop Memory

Arquitectura

Claude Desktop (Sonnet)
        │ MCP Protocol (STDIO)
        ▼
Chronica MCP Server (Python)
  └── src/chronica/
        ├── tools.py       # 10 MCP tools
        ├── opening.py     # Context generation
        ├── summarize.py   # Summary generation
        ├── store.py       # SQLite persistence
        └── timeparse.py   # Relative time parsing
        │ SQLite
        ▼
data/chronica.sqlite3

Filosofía de diseño: Chronica es la fuente única de verdad para el tiempo y la estructura de la memoria. Claude actúa puramente como la interfaz — previniendo alucinaciones al confiar solo en la salida estructurada de Chronica.

Requisitos

Python 3.10+
Claude Desktop (con soporte MCP)
Windows / macOS

Instalación

Configuración rápida (recomendada)

Ejecuta lo siguiente en la raíz del proyecto para configurar el entorno virtual, los paquetes de dependencias y la configuración de Claude Desktop de una sola vez.

# Windows (PowerShell)
.\setup.ps1

# Windows (cmd)
setup.bat

# macOS / Linux
chmod +x setup.sh
./setup.sh

Después de completar, reinicia Claude Desktop / Claude Code.

Si usas Claude Code
Después de la configuración, abre la carpeta de Chronica e inicia una conversación; Chronica se cargará automáticamente mediante .mcp.json. Es posible que se te solicite permiso para usar el servidor MCP la primera vez.

Si aparece "No se han añadido servidores MCP"
La versión MSIX descargada desde claude.ai usa una ruta de configuración diferente. Al ejecutar .\setup.ps1 nuevamente, la configuración se escribirá en ambas rutas.

Configuración manual

1. Clonar el repositorio

git clone https://github.com/Nic9dev/Chronica.git
cd Chronica

2. Crear el entorno virtual

python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS
source .venv/bin/activate

3. Instalar las dependencias

pip install -r requirements.txt

4. Configurar Claude Desktop

Agrega lo siguiente al archivo de configuración de Claude Desktop (claude_desktop_config.json).

Ubicación del archivo de configuración:

Windows (versión MSIX / descargado desde claude.ai): %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\claude_desktop_config.json
Windows (versión clásica / instalación exe): %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Al ejecutar .\setup.ps1, se detectan automáticamente la versión MSIX y la clásica, y la configuración se escribe en la ruta adecuada.

{
  "mcpServers": {
    "chronica": {
      "command": "C:/path/to/Chronica/.venv/Scripts/python.exe",
      "args": ["C:/path/to/Chronica/run_server.py"],
      "env": {
        "PYTHONPATH": "C:/path/to/Chronica/src"
      }
    }
  }
}

⚠️ Reemplaza la parte de C:/path/to/Chronica con tu ruta real.
⚠️ En Windows, usa / (no se permite \).

5. Reiniciar Claude Desktop

Después de la configuración, reinicia Claude Desktop.
Inicia una nueva conversación y podrás confirmar que Claude carga la memoria automáticamente.

Uso

Después del primer inicio

Al iniciar una nueva conversación, Claude llama a chronica_compose_opening para cargar el contexto. Se asume que debes pasar el nombre del proyecto actual en project (si no lo sabes, confírmalo con chronica_list_threads u otras herramientas). Las instrucciones del lado de MCP indican que esta herramienta debe llamarse antes que otras al solicitar verificación de estado o memoria.

Activar/desactivar el conector (se puede cambiar por conversación)

Abre el menú con el botón "+" o "/" en el chat y activa o desactiva Chronica desde "Conectores".

Conector	Guardado de memoria	Recuperación de memoria	Reconocimiento de tiempo
ACTIVADO	Automático	Automático	Sí
DESACTIVADO	No se realiza	No se realiza	No

ACTIVADO: El guardado, la recuperación y el reconocimiento de tiempo se realizan automáticamente.
DESACTIVADO: Las herramientas de Chronica no se utilizan en esa conversación. Ideal para consultas temporales sin usar memoria.

Uso diario

Guardar memoria: Simplemente conversa con normalidad. Claude guarda automáticamente la información importante.
Buscar memoria: Pregunta naturalmente, por ejemplo, "dime lo que decidimos la semana pasada".
Interfaz de curación: Cuando se acumulen memorias, puedes organizarlas con lo siguiente:

# Windows (PowerShell)
.\run_curation.ps1

# Windows (cmd)
run_curation.bat

# または
python -m streamlit run app_curation.py

💡 Consejos: Continuidad entre conversaciones

Inicio de conversación: En chronica_compose_opening, asegúrate de pasar project="..." (para evitar que se mezclen memorias de otros proyectos). Si el nombre es ambiguo, confírmalo con chronica_list_threads antes de llamar.
Registros detallados: compose_opening solo muestra un resumen de las 5 entradas más recientes. Para registros de trabajo largos, continúa llamando a chronica_search con project (y la etiqueta volN si es necesario).

Al iniciar una nueva conversación (vol.2, vol.3, etc.), por ejemplo, puedes decir lo siguiente para extraer con precisión el contenido del trabajo anterior desde Chronica:

Llama a chronica_search con el proyecto "nombre del proyecto" y la etiqueta "vol2", y verifica el contenido del trabajo anterior y los elementos pendientes.

⚠️ Si solo dices "verifica el trabajo anterior", Claude podría consultar su propio historial de conversación en lugar de Chronica. La clave es especificar explícitamente compose_opening con project y el proyecto/etiqueta en la búsqueda.

Hoja de ruta

Fase 2 (próximamente)

Detección automática de memorias duplicadas (TF-IDF + similitud de coseno)
Función de eliminación por lotes (selección múltiple)
Búsqueda de texto completo
Función de exportación (JSON / CSV)

Fase 3 (futuro)

Sincronización en la nube (Supabase + E2EE)
Soporte para múltiples dispositivos

Fase 4 (futuro)

SaaS y soporte multiinquilino

Licencia

Licencia MIT — consulta LICENSE para más detalles.

Autor

Nic9 （にく９）
Sin experiencia previa en programación, construyó múltiples sistemas de forma autodidacta junto con IA.
Chronica nació como "una base personal para mantener una relación a largo plazo con la IA".

Contribuciones

¡Las issues y los PRs son bienvenidos!
Informes de errores y solicitudes de funciones a través de Issues.