Roampal — Ergebnisbasierter persistenter Speicher MCP-Server

Warum?

KI-Coding-Assistenten vergessen alles zwischen den Sitzungen. Du erklärst deine Architektur, deine Vorlieben, deine Konventionen — immer wieder. Wenn sie schlechte Ratschläge geben, gibt es keinen Mechanismus, um daraus zu lernen.

Roampal ist ein MCP-Server, der deiner KI ein persistentes, ergebnisbasiertes Gedächtnis über jede Sitzung hinweg gibt. Gute Ratschläge werden befördert. Schlechte Ratschläge werden herabgestuft. Deine KI lernt, was funktioniert und was nicht — automatisch, ohne Änderungen am Arbeitsablauf.

Benchmarks

85,8 % bei LoCoMo (nicht-adversariell, End-to-End-Antwortgenauigkeit) — validiert an 1.986 Fragen über 10 Konversationen mit doppelter Bewertung.

Die Benchmark-Pipeline läuft auf einer einzelnen GPU ohne Cloud-Abhängigkeiten. Roampal selbst läuft auf der CPU — keine GPU erforderlich. Vollständige Methodik, Daten und Evaluierungsskripte: roampal-labs

Paper: "Beyond Ingestion: What Conversational Memory Learning Reveals on a Corrected LoCoMo Benchmark" (Logan Teague, April 2026)

Schnellstart

pip install roampal
roampal init

Erkennt installierte Tools automatisch. Starte deinen Editor neu und beginne zu chatten.

Ziel ein spezifisches Tool: roampal init --claude-code oder roampal init --opencode

Die Kernschleife ist identisch — beide Plattformen injizieren Kontext, erfassen Austauschvorgänge und bewerten Ergebnisse. Der Bereitstellungsmechanismus unterscheidet sich:

Claude Code fordert das Haupt-LLM auf, jeden Austausch über das score_memories Tool zu bewerten. OpenCode bewertet sich nie selbst — ein unabhängiger Sidecar (ein separater API-Aufruf) überprüft jeden Austausch als Dritter, was die Voreingenommenheit bei der Selbsteinschätzung entfernt. Das score_memories Tool ist bei OpenCode nicht registriert. Während roampal init oder roampal sidecar setup erkennt Roampal lokale Modelle (Ollama, LM Studio, etc.) und lässt dich ein Bewertungsmodell wählen. Falls konfiguriert, haben diese Vorrang (Zen wird aus Datenschutzgründen übersprungen). Ein günstiges oder lokales Modell funktioniert hervorragend — die Bewertung benötigt kein leistungsstarkes Modell. Standardmäßig werden Zen-freie Modelle (remote, best-effort) verwendet, wenn du das Setup überspringst.

Funktionsweise

Wenn du eine Nachricht tippst, injiziert Roampal automatisch relevanten Kontext, bevor deine KI ihn sieht:

Du tippst:

fix the auth bug

Deine KI sieht:

═══ 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

Keine manuellen Aufrufe. Keine Änderungen am Arbeitsablauf. Es funktioniert einfach.

Die Schleife

1. Du tippst eine Nachricht

2. Roampal injiziert automatisch relevanten Kontext (Hooks in Claude Code, Plugin in OpenCode)

3. KI antwortet mit vollem Bewusstsein über deine Historie, Vorlieben und was zuvor funktioniert hat

4. Ergebnis bewertet — gute Ratschläge werden befördert, schlechte herabgestuft

5. Wiederholen — das System wird mit jedem Austausch intelligenter

Fünf Speichersammlungen

Befehle

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)

MCP-Tools

Deine KI erhält diese Speicher-Tools:

Wie die Bewertung funktioniert: Die Hooks von Claude Code fordern das Haupt-LLM auf, bei jedem Turn score_memories aufzurufen. OpenCode verwendet einen unabhängigen Sidecar, der im Hintergrund lautlos bewertet — das Modell sieht nie einen Bewertungs-Prompt und score_memories ist nicht als Tool registriert. Wenn der Sidecar nicht verfügbar ist, wird der Benutzer aufgefordert, roampal sidecar setup auszuführen. Wähle dein Bewertungsmodell während roampal init oder über roampal sidecar setup.

Wie Roampal im Vergleich abschneidet

┌─────────────────────────────────────────────────────────┐
│  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    │
└─────────────────────────────────────────────────────────┘

Siehe dev/docs/ für vollständige technische Details.

Anforderungen

• Python 3.10+

• Eines von: Claude Code oder OpenCode

• Plattformen: Windows, macOS, Linux (hauptsächlich auf Windows entwickelt und getestet)

• RAM: ~800MB verfügbar (Cross-Encoder Reranker + Embeddings + ChromaDB)

• Festplatte: ~500MB für Modelle (mehrsprachiges Embedding + Reranker, wird bei erster Nutzung automatisch heruntergeladen)

• CPU: Jeder moderne x86-64 Prozessor mit AVX2 (Intel Haswell 2013+ / AMD Excavator 2015+)

• GPU: Nicht erforderlich — alle Inferenzen laufen auf der CPU via ONNX Runtime

Fehlerbehebung

• Starte Claude Code neu (Hooks laden beim Start)

• Überprüfe HTTP-Server: curl http://127.0.0.1:27182/api/health

• Überprüfe, ob ~/.claude.json den roampal-core MCP-Eintrag mit dem korrekten Python-Pfad enthält

• Überprüfe das Ausgabe-Panel von Claude Code auf MCP-Fehler

• Stelle sicher, dass du roampal init --opencode ausgeführt hast

• Überprüfe, ob der Server automatisch gestartet wurde: curl http://127.0.0.1:27182/api/health

• Falls nicht, starte ihn manuell: roampal start

Das ist zu erwarten. Roampal verfügt über Selbstheilung — wenn der HTTP-Server nicht mehr reagiert, wird er automatisch neu gestartet und erneut versucht.

Immer noch festgefahren? Bitte deine KI um Hilfe — sie kann Protokolle lesen und Roampal-Probleme direkt debuggen.

Support

Roampal Core ist komplett kostenlos und Open Source.

• Entwicklung unterstützen: roampal.gumroad.com

• Feature-Ideen & Feedback: Discord

• Fehlerberichte: GitHub Issues

• Hilfe bei KI-Gedächtnis benötigt? Kontaktiere: roampal@protonmail.com | LinkedIn

Lizenz

Apache 2.0