roampal-core

Roampal Core is an MCP server that provides outcome-based persistent memory for AI coding assistants. It integrates memory collections such as working context, history, patterns, memory_bank, and books, enabling your AI to remember preferences, past conversations, and learned solutions across sessions. The server exposes memory tools like search_memory, add_to_memory, update_memory, delete_memory, score_memories (Claude Code only), and record_response. Start by initializing Roampal, which auto-detects installed tools and configures scoring models if available, then run the HTTP server to begin using your AI with enhanced memory. When integrated with Claude Code, OpenCode, or similar tools, Roampal injects context automatically and scores outcomes to promote good advice and demote bad advice.

To use the MCP tools, you typically interact through the Roampal CLI or editor plugins. You can run roampal init to auto-detect tools and roampal start to launch the HTTP server. When typing messages to your AI, Roampal injects known context such as memory collections and preferences, so the AI has continuity across sessions without requiring manual workflow changes.

Prerequisites:

• Python 3.10+ installed on your system
• Internet access to install Python packages
• Optional: editor integration that can communicate with the Roampal HTTP server

Install steps:

1. Create and activate a Python environment (optional but recommended): python -m venv venv source venv/bin/activate # macOS/Linux venv\Scripts\activate # Windows

2. Install Roampal from PyPI: pip install roampal

3. Initialize Roampal (auto-detects tools and configures scoring models if available): roampal init

4. Start the Roampal HTTP server: roampal start

5. Verify the server is running (e.g., via roampal status or by making a test request). If you need non-default settings, you can provide a configuration file and reference it with ROAMPAL_CONFIG.

Tips and common issues:

• If using OpenCode, ensure the sidecar setup is completed for independent scoring (roampal sidecar setup).
• The scoring model selection can be configured during roampal init or via sidecar setup; Zen models are skip-priority for privacy if not configured.
• Environment variables like ROAMPAL_CONFIG and ROAMPAL_LOG_LEVEL can help customize behavior and logging.
• If the server fails to start, check Python dependencies, ensure no port conflicts, and look for error logs in the console output.
• The available MCP tools (search_memory, add_to_memory, update_memory, delete_memory, score_memories, record_response) enable you to manage memories and outcomes programmatically.
• For editor integrations, restart your editor after roampal init and roampal start to ensure the plugins receive the updated context and server URL.