mcp-zip 🗜️

Memoria comprimida para agentes de IA.

mcp-zip es un servidor MCP que comprime el contexto de tu agente de IA. En vez de leer archivos completos (miles de tokens), busca solo lo relevante (decenas de tokens). Como un ZIP, pero para la memoria del agente.

El Problema

Tu agente de IA olvida todo cada vez que termina una sesión. Para recordar, tiene que leer archivos completos de contexto — consumiendo miles de tokens en cada conversación. Al final del día, llegás al rate limit.

La Solución

mcp-zip comprime la memoria del agente en archivos .md compactos, optimizados para consumo de LLMs. Con búsqueda FTS5 + TF-IDF, tu agente encuentra lo relevante en milisegundos sin leer archivos completos.

Arquitectura

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  .md files   │────▶│  .json cache │────▶│  SQLite      │
│  (store)     │     │  (estructura)│     │  (índice)    │
│  git-friendly│     │  parseo rápido│    │  FTS5+TF-IDF │
└──────────────┘     └──────────────┘     └──────────────┘
       │                    │                    │
       ▼                    ▼                    ▼
  Humanos leen       APIs acceden        Agente busca
  y commitean        programátic.        instantáneo

Flujo de Trabajo

INICIAR SESIÓN:
  memoria_iniciar("ferreteria")
  → Auto-archiva entradas >30 días
  → ✅ Proyecto activo

ESCRIBIR:
  memoria_escribir("ferreteria", "bug", "Color falla", ...)
  → Guarda en .md (git)
  → Genera .json (cache)
  → Indexa en SQLite (búsqueda)

BUSCAR:
  memoria_buscar("ferreteria", "color detection")
  → SQLite FTS5 + TF-IDF busca (~700 tokens)
  → Devuelve solo entradas relevantes

LEER:
  memoria_leer("ferreteria", "resumen")
  → Lee .md completo (~500 tokens)
  → Solo para contexto general

Instalación

pip install mcp-zip

Configurar en tu Editor

Zed

Agrega en ~/.config/zed/settings.json:

{
  "context_servers": {
    "zip": {
      "command": "mcp-zip"
    }
  }
}

Claude Desktop

Agrega en claude_desktop_config.json:

{
  "mcpServers": {
    "zip": {
      "command": "mcp-zip"
    }
  }
}

Cursor

Agrega en .cursor/mcp.json:

{
  "mcpServers": {
    "zip": {
      "command": "mcp-zip"
    }
  }
}

Cualquier Cliente MCP

{
  "mcpServers": {
    "zip": {
      "command": "mcp-zip",
      "env": {
        "MEMORIA_ROOT": "~/.memoria"
      }
    }
  }
}

Herramientas

Herramienta	Descripción	Tokens
memoria_iniciar	Crea/reactiva proyecto + auto-archiva	~50
memoria_escribir	Registra entrada (bug, decisión, plan)	~100
memoria_buscar	Búsqueda semántica FTS5 + TF-IDF	~700
memoria_leer	Lee archivo completo	~500-5000
memoria_resumen	Resumen compacto del estado	~500
memoria_listar	Lista todos los proyectos	~100
memoria_archivar	Archiva entradas >30 días en bóveda	~50
memoria_importar	Migra .md existentes al sistema	~200
memoria_exportar	Exporta archivo de memoria	variable
memoria_estadisticas	Métricas de uso y ahorro de tokens	~300
memoria_sincronizar	Sync JSON + SQLite de todos los proyectos	~500
memoria_exportar_zip	Exporta proyecto a formato .mcp-zip	~200
memoria_importar_zip	Importa proyecto desde .mcp-zip	~300
memoria_listar_zip	Lista contenido de un .mcp-zip	~100

Flujo Óptimo (Ahorra Tokens)

❌ Mal (consume ~50,000 tokens/sesión)

# Leer TODO el contexto cada vez
memoria_leer("ferreteria", "errores")      # 3,716 tokens
memoria_leer("ferreteria", "decisiones")    # 5,901 tokens
memoria_leer("ferreteria", "implementacion") # 2,862 tokens

✅ Bien (consume ~3,500 tokens/sesión)

# Resumen general
memoria_resumen("ferreteria")              # 500 tokens

# Búsqueda específica
memoria_buscar("ferreteria", "parser")     # 700 tokens
memoria_buscar("ferreteria", "color")      # 700 tokens

# Lectura solo si es necesario
memoria_leer("ferreteria", "resumen")      # 500 tokens

Ahorro: 93% de tokens por sesión.

Formato Compacto

mcp-zip usa un formato .md optimizado para modelos de IA:

### bug | 2026-07-14 | resuelto
Color detection no funciona
ctx: Pinturas Tekbond/Miura se fusionan
root: paso 8 parser FGP, result.attributes sobreescribe objeto
fix: result.attributes = { ...result.attributes, features }
tags: parser,fgp,colores
files: src/services/normalization/parsers/fgp.parser.ts

vs formato tradicional (2x más tokens):

## [2026-07-14] Bug: Color detection no funciona 🟢 Resuelto

- **Contexto**: Pinturas Tekbond/Miura se fusionan al no detectar color
- **Causa raíz**: En el paso 8 del parser FGP, `result.attributes = { features: ... }` SOBREESCRIBÍA el objeto
- **Solución**: Cambiar por `result.attributes = { ...result.attributes, features: ... }`
- **Estado**: 🟢 Resuelto

Bóveda de Archivado

Las entradas resueltas con más de 30 días se archivan automáticamente al iniciar sesión:

~/.memoria/proyectos/ferreteria/
├── errores.md          ← Entradas activas
├── errores.json        ← Cache estructurado
├── decisiones.md       ← Entradas activas
├── decisiones.json     ← Cache estructurado
├── memoria.db          ← Índice FTS5 + TF-IDF
└── boveda/
    ├── errores-2026-06.md      ← Archivados de junio
    ├── errores-2026-06.json    ← Cache de archivados
    ├── decisiones-2026-06.md
    └── decisiones-2026-06.json

Stores de Almacenamiento

Store	Formato	Para Qué	Quién lo Lee
.md	Markdown compacto	Git, humanos, backup	Cualquiera
.json	JSON estructurado	Acceso programático	Python, APIs
.db	SQLite FTS5 + TF-IDF	Búsqueda instantánea	Motor de búsqueda

Migración

Si ya tenés archivos .md de contexto existentes:

# El agente llama:
memoria_importar("ferreteria", "/home/user/proyectos/ferreteria/context/")
→ 📥 Importación completada: 5 archivos, 23 entradas
→ 📄 JSON sincronizado automáticamente

Variables de Entorno

Variable	Descripción	Default
MEMORIA_ROOT	Directorio raíz de almacenamiento	~/.memoria

Formato .mcp-zip

Formato comprimido para exportar/importar proyectos completos:

# Exportar proyecto
memoria_exportar_zip("ferreteria")
→ 📦 ferreteria.mcp-zip (24.5 KB → 8.2 KB comprimido)

# Importar proyecto
memoria_importar_zip("/backup/ferreteria.mcp-zip")
→ 📥 Proyecto 'ferreteria' importado (47 entradas)

# Listar contenido
memoria_listar_zip("ferreteria.mcp-zip")
→ 📋 Contenido:
   - errores.md (12 KB)
   - errores.json (8 KB)
   - decisiones.md (18 KB)
   - ...

Estadísticas

memoria_estadisticas("ferreteria")
→ 📊 Estadísticas:
   - Entradas: 47 (23 bugs, 15 decisiones, 9 planes)
   - Activas: 31 | Archivadas: 16
   - 💰 Ahorro: 93% (46,500 tokens/sesión)

Sincronización

memoria_sincronizar()
→ 🔄 Sincronizando todos los proyectos...
   - ferreteria: ✅ JSON + SQLite reconstruido
   - matucho: ✅ JSON + SQLite reconstruido

Stats del Proyecto

Líneas de código:  ~2,200
Tests:             35/35 ✅
Dependencias:      2 (fastmcp, pyyaml)
Formato:           .md + .json + SQLite
Búsqueda:          FTS5 + TF-IDF (sin ML)

Licencia

MIT — Ver LICENSE

---

mcp-zip — Comprime la memoria de tu agente. Ahorra tokens. Nunca olvide. 🗜️