Content
# mcp-zip 🗜️
**Memoria comprimida para agentes de IA.**
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://modelcontextprotocol.io)
> **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
```bash
pip install mcp-zip
```
## Configurar en tu Editor
### Zed
Agrega en `~/.config/zed/settings.json`:
```json
{
"context_servers": {
"zip": {
"command": "mcp-zip"
}
}
}
```
### Claude Desktop
Agrega en `claude_desktop_config.json`:
```json
{
"mcpServers": {
"zip": {
"command": "mcp-zip"
}
}
}
```
### Cursor
Agrega en `.cursor/mcp.json`:
```json
{
"mcpServers": {
"zip": {
"command": "mcp-zip"
}
}
}
```
### Cualquier Cliente MCP
```json
{
"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:
```markdown
### 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):**
```markdown
## [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:
```bash
# 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:
```bash
# 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
```bash
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
```bash
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](LICENSE)
---
**mcp-zip** — Comprime la memoria de tu agente. Ahorra tokens. Nunca olvide. 🗜️
