Roampal

Persistent Memory for AI Coding Tools

Two commands. Claude Code gets persistent memory.

Installation

pip install roampal
roampal init

That's it. Restart Claude Code and your AI remembers everything.

Note: No roampal start needed! The MCP server auto-starts the hook server when Claude Code launches.

How It Works

The Magic: Automatic Context Injection

When you type a message:

You see:

Help me fix this auth bug

The AI sees:

<roampal-score-required>
Score the previous exchange before responding.
Previous: User asked "How do I configure TypeScript?" You answered "..."
Call score_response(outcome="worked|failed|partial|unknown") FIRST.
</roampal-score-required>

═══ KNOWN CONTEXT ═══
• Alex, backend engineer at StartupCo (memory_bank)
• JWT refresh token pattern worked for auth issues (92% proven, patterns)
═══ END CONTEXT ═══

Help me fix this auth bug

You never have to ask "remember when..." - it's automatic.

How?

1. UserPromptSubmit Hook: Before Claude sees your message, Roampal injects relevant context + scoring prompt
2. Outcome Learning: When things work (score_response(worked)), memories get promoted. When they fail, they get demoted.
3. Five Memory Collections:
   • memory_bank: Your identity, preferences, goals (never decays)
   • patterns: Proven solutions (auto-promoted from history)
   • history: Past conversations
   • working: Current session context
   • books: Uploaded reference docs

Commands

roampal init      # Configure Claude Code (one-time)
roampal ingest    # Add documents (.txt, .md, .pdf) to books collection
roampal books     # List all ingested books
roampal remove    # Remove a book by title
roampal status    # Check if server is running
roampal stats     # View memory statistics

MCP Tools

The AI has these tools for memory access:

Tool	Description
get_context_insights	Get user profile + relevant memories
search_memory	Search across collections
add_to_memory_bank	Store permanent facts
update_memory	Update existing memories
delete_memory	Delete outdated info
score_response	Score previous exchange (prompted by hook)
record_response	Store key takeaways (optional)

What's Different?

Vanilla Claude Code	With Roampal
Forgets everything between sessions	Remembers you, your preferences, what worked
You repeat context every time	Context injected automatically
No learning from mistakes	Outcomes tracked - bad advice gets demoted
No document memory	Ingest docs, they're searchable forever

Requirements

• Python 3.10+
• Claude Code (VS Code extension or CLI)
• Platforms: Windows, macOS, Linux (macOS/Linux community-tested)

Troubleshooting

Hooks not working?

• Restart Claude Code (hooks load on startup)
• Check HTTP server: curl http://127.0.0.1:27182/api/health

MCP not connecting?

• Verify ~/.claude/mcp.json exists and has correct Python path
• Check Claude Code output panel for MCP errors

Context not appearing?

• Make sure you ran roampal init
• Restart Claude Code after init

Still stuck? Ask Claude Code for help - it can read logs and debug Roampal issues directly.

Architecture

┌─────────────────────────────────────────────────────────┐
│  pip install roampal && roampal init                    │
│    → Configures hooks + MCP in ~/.claude/               │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  User opens Claude Code                                 │
│    → Claude loads MCP server (roampal.mcp.server)       │
│    → MCP server spawns HTTP hook server (port 27182)    │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  User types message                                     │
│    → UserPromptSubmit hook calls HTTP server            │
│    → Server returns context + scoring prompt            │
│    → AI sees context, scores previous, responds         │
│    → Stop hook stores exchange for next turn            │
└─────────────────────────────────────────────────────────┘

License

Apache 2.0

Credits

Built with love for the AI coding community. Based on learnings from building Roampal Desktop.