Roampal — Servidor MCP de memoria persistente basada en resultados

¿Por qué?

Los asistentes de programación con IA olvidan todo entre sesiones. Explicas tu arquitectura, tus preferencias, tus convenciones... una y otra vez. Cuando dan un mal consejo, no hay mecanismo para aprender de ello.

Roampal es un servidor MCP que le da a tu IA una memoria persistente basada en resultados en cada sesión. Los buenos consejos se promueven. Los malos consejos se degradan. Tu IA aprende qué funciona y qué no, automáticamente, sin cambios en el flujo de trabajo.

Benchmarks

85.8% en LoCoMo (no adversarial, precisión de respuesta de extremo a extremo) — validado en 1,986 preguntas a través de 10 conversaciones con doble calificación.

La canalización de referencia se ejecuta en una sola GPU sin dependencias en la nube. Roampal en sí mismo se ejecuta en la CPU; no se requiere GPU. Metodología completa, datos y scripts de evaluación: roampal-labs

Artículo: "Beyond Ingestion: What Conversational Memory Learning Reveals on a Corrected LoCoMo Benchmark" (Logan Teague, abril de 2026)

Inicio rápido

pip install roampal
roampal init

Detecta automáticamente las herramientas instaladas. Reinicia tu editor y comienza a chatear.

Dirígete a una herramienta específica: roampal init --claude-code o roampal init --opencode

El bucle principal es idéntico: ambas plataformas inyectan contexto, capturan intercambios y califican resultados. El mecanismo de entrega difiere:

Claude Code solicita al LLM principal que califique cada intercambio mediante la herramienta score_memories. OpenCode nunca se autocalifica: un sidecar independiente (una llamada API separada) revisa cada intercambio como un tercero, eliminando el sesgo de autoevaluación. La herramienta score_memories no está registrada en OpenCode. Durante roampal init o roampal sidecar setup, Roampal detecta modelos locales (Ollama, LM Studio, etc.) y te permite elegir un modelo de calificación. Si se configuran, estos tienen prioridad (Zen se omite por privacidad). Un modelo barato o local funciona muy bien; la calificación no necesita un modelo potente. Se utilizan por defecto modelos Zen gratuitos (remotos, de mejor esfuerzo) si omites la configuración.

Cómo funciona

Cuando escribes un mensaje, Roampal inyecta automáticamente el contexto relevante antes de que tu IA lo vea:

Tú escribes:

fix the auth bug

Tu IA ve:

═══ KNOWN CONTEXT ═══
• JWT refresh pattern fixed auth loop [id:patterns_a1b2] (3d, 90% proven, patterns)
• User prefers: never stage git changes [id:mb_c3d4] (memory_bank)
═══ END CONTEXT ═══

fix the auth bug

Sin llamadas manuales. Sin cambios en el flujo de trabajo. Simplemente funciona.

El bucle

1. Tú escribes un mensaje

2. Roampal inyecta contexto relevante automáticamente (hooks en Claude Code, plugin en OpenCode)

3. La IA responde con plena conciencia de tu historial, preferencias y lo que funcionó antes

4. Resultado calificado: los buenos consejos se promueven, los malos se degradan

5. Repetir: el sistema se vuelve más inteligente en cada intercambio

Cinco colecciones de memoria

Comandos

roampal init                # Auto-detect and configure installed tools
roampal init --claude-code  # Configure Claude Code explicitly
roampal init --opencode     # Configure OpenCode explicitly
roampal init --no-input     # Non-interactive setup (CI/scripts)
roampal start               # Start the HTTP server manually
roampal stop                # Stop the HTTP server
roampal status              # Check if server is running
roampal status --json       # Machine-readable status (for scripting)
roampal stats               # View memory statistics
roampal stats --json        # Machine-readable statistics (for scripting)
roampal doctor              # Diagnose installation issues
roampal summarize           # Summarize long memories (retroactive cleanup)
roampal score               # Score the last exchange (manual/testing)
roampal context             # Output recent exchange context
roampal ingest <file>       # Add documents to books collection
roampal books               # List all ingested books
roampal remove <title>      # Remove a book by title
roampal sidecar status      # Check scoring model configuration (OpenCode)
roampal sidecar setup       # Configure scoring model (OpenCode)
roampal sidecar test        # Test scoring model response format (OpenCode)
roampal retag               # Re-extract tags on memories using sidecar LLM
roampal sidecar disable     # Remove scoring model configuration (OpenCode)

Herramientas MCP

Tu IA obtiene estas herramientas de memoria:

Cómo funciona la calificación: Los hooks de Claude Code solicitan al LLM principal que llame a score_memories en cada turno. OpenCode utiliza un sidecar independiente que califica silenciosamente en segundo plano: el modelo nunca ve un prompt de calificación y score_memories no está registrada como herramienta. Si el sidecar no está disponible, una advertencia solicita al usuario que ejecute roampal sidecar setup. Elige tu modelo de calificación durante roampal init o mediante roampal sidecar setup.

Comparativa de Roampal

┌─────────────────────────────────────────────────────────┐
│  pip install roampal && roampal init                    │
│    Claude Code: hooks + MCP → ~/.claude/                │
│    OpenCode:    plugin + MCP → ~/.config/opencode/      │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  HTTP Hook Server (port 27182)                          │
│    Auto-started on first use, self-heals on failure     │
│    Manual control: roampal start / roampal stop         │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  User types message                                     │
│    → Hook/plugin calls HTTP server for context          │
│    → AI sees relevant memories, responds                │
│    → Exchange stored, scored (hooks or sidecar)         │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  Single-Writer Backend                                  │
│    FastAPI → UnifiedMemorySystem → ChromaDB             │
│    All clients share one server, isolated by session    │
└─────────────────────────────────────────────────────────┘

Consulta dev/docs/ para obtener detalles técnicos completos.

Requisitos

• Python 3.10+

• Uno de: Claude Code o OpenCode

• Plataformas: Windows, macOS, Linux (desarrollado y probado principalmente en Windows)

• RAM: ~800MB disponibles (reordenador cross-encoder + embeddings + ChromaDB)

• Disco: ~500MB para modelos (embedding multilingüe + reordenador, descargados automáticamente en el primer uso)

• CPU: Cualquier procesador x86-64 moderno con AVX2 (Intel Haswell 2013+ / AMD Excavator 2015+)

• GPU: No requerida — toda la inferencia se ejecuta en la CPU mediante ONNX Runtime

Solución de problemas

• Reinicia Claude Code (los hooks se cargan al inicio)

• Comprueba el servidor HTTP: curl http://127.0.0.1:27182/api/health

• Verifica que ~/.claude.json tenga la entrada MCP roampal-core con la ruta de Python correcta

• Comprueba el panel de salida de Claude Code para ver errores de MCP

• Asegúrate de haber ejecutado roampal init --opencode

• Comprueba que el servidor se inició automáticamente: curl http://127.0.0.1:27182/api/health

• Si no, inícialo manualmente: roampal start

Esto es esperado. Roampal tiene autorreparación: si el servidor HTTP deja de responder, se reinicia automáticamente y se reintenta.

¿Sigues atascado? Pide ayuda a tu IA: puede leer registros y depurar problemas de Roampal directamente.

Soporte

Roampal Core es completamente gratuito y de código abierto.

• Apoya el desarrollo: roampal.gumroad.com

• Ideas de funciones y comentarios: Discord

• Informes de errores: GitHub Issues

• ¿Necesitas ayuda con la memoria de IA? Contáctanos: roampal@protonmail.com | LinkedIn

Licencia

Apache 2.0