Roampal (Alpha) - AI That Grows With You

Q: How is this different from cloud AI memory (ChatGPT, Claude, etc.)?

Cloud AI stores what you say. Roampal learns what works. Three key differences: 1) It learns from results - when something helps you, Roampal remembers. When it doesn't work, it learns from that too. 2) Local-first privacy - your data stays on your machine. No cloud servers, no recurring subscriptions. 3) True ownership - you own your data, your models, your memory. Export everything anytime.

Q: What models does it support?

Works with many popular AI models including Llama (Meta's free models), Qwen (great for many languages), and Mixtral (fast and efficient). Pick the one that works best on your computer and install from Settings.

Q: Does it work offline?

Yes! After downloading models, Roampal works completely offline. No internet required.

Q: What are the system requirements?

Minimum: 8GB RAM, 10GB free disk space. Recommended: 16GB RAM and a decent graphics card for faster responses.

Q: How do I export my data?

Easy way: Go to Settings → Export. Pick what you want to backup and download a zip file. Manual: All your data is stored in regular files on your computer. Just copy the data folder to backup.

Q: Why charge if it's open source?

The code is free on GitHub. The $9.99 gets you: pre-packaged executable (no Python setup required), bundled dependencies, tested build (guaranteed to work), and lifetime updates (all future releases included). Technical users can View on GitHub for free.

Q: Is Roampal's advice always reliable?

No. Roampal uses AI models that can generate incorrect information, hallucinate facts, or reflect training biases. Always verify critical information from authoritative sources. Do not rely on AI-generated content for medical, legal, or financial advice, safety-critical systems, or production code without thorough review.

Q: What are the MCP tools and what do they do?

When you connect Roampal to Claude Code, Cursor, or other MCP-compatible tools, they get access to memory tools: search_memory (finds relevant memories), get_context_insights (quick topic lookup), record_response (records outcomes - how Roampal learns), add_to_memory_bank (stores permanent facts), update_memory (corrects existing memories), and archive_memory (removes outdated info). Your AI uses these automatically during conversation.

The Problem With AI Memory Today

Most AI memory finds things that sound similar to your question.
But sounding similar doesn't mean it helped you before.

Here's an example:

You ask your AI: "What's a good restaurant for a date night?"

Your AI remembers two places you've tried before:

Memory A:

"That new romantic sushi place downtown"

You went there - food was disappointing

Memory B:

"The Italian place on Main Street"

You loved it - amazing experience

Regular AI picks Memory A because "romantic" and "downtown" sound like good date words.
Roampal picks Memory B because it remembers you actually had a great time there.

How does it know what worked?

Just talk naturally. The AI reads your response, determines if you were satisfied, and scores the memory in Roampal. No buttons to click, no ratings to give - it learns from the conversation itself.

We tested this:

Questions designed to trick the AI into giving the wrong answer.

Approach	Got It Right	Improvement
Standard AI search	10%	-
+ Smarter ranking	20%	+10 pts
+ Learning from outcomes	50%	+40 pts

Smarter ranking helps a little. Outcome tracking helps 4× more.

It gets better the more you use it

We measured how well it finds the right answer over time.

10%

Cold start (0 uses)

100%

As you use it

4×

Better than ranking alone

The more you use it, the better it gets at finding what actually helps you.

Why this matters:

Better answers with less noise. Roampal only retrieves what's proven helpful, not everything that sounds related. That means lower API costs, faster responses, and more accurate answers.

Technical details for researchers

Coding (30): p=0.001, d=7.49 • Finance (100): p<0.001, χ²=98 • Learning: p=0.005, d=13.4
Full methodology & reproducible benchmarks

How Memories Are Organized

How Memories Move From New to Permanent

Working (24h)

Current context

Used successfully twice

↓

History (30d)

Recent conversations

Helped you many times

↓

Patterns (∞)

Proven solutions

Permanent storage

Permanent Collections (No Promotion)

Memory Bank

Your preferences & context

AI adds these automatically

Books

Reference docs

User-uploaded

Outcome Detection Algorithm

Roampal uses LLM to detect outcomes from natural language:

Positive signals: "that worked!", "perfect", "exactly what I needed"
Negative signals: "didn't work", "that failed", "not helpful"
Implicit signals: Topic changes, abandoning approach, asking similar question

# LLM analyzes conversation and detects outcome
if outcome == "worked":
    score += 0.2  # Positive outcome
elif outcome == "failed":
    score -= 0.3  # Negative outcome
elif outcome == "partial":
    score += 0.05  # Partial success

Learns Your Patterns

Roampal builds 3 interconnected Knowledge Graphs that learn different aspects of your memory:

1. Routing KG - "Where to Look"

Learns which memory collections answer which types of questions.

You ask: "What books did I read about investing?"

System learned: Questions about "books" → books collection (85% success)

Result: Searches books first, skips less relevant collections → faster answers

2. Content KG - "What's Connected"

Extracts people, places, tools, and concepts from your memories and tracks relationships.

Your memories mention: "Sarah Chen works at TechCorp as an engineer"

System extracts: Sarah Chen → TechCorp → engineer (with quality scores)

Result: "Who works at TechCorp?" → finds Sarah even without exact keyword match

3. Action-Effectiveness KG - "What Works"

Tracks which tools and actions succeed or fail in different contexts.

During a quiz: AI uses create_memory() to answer questions

System tracks: create_memory in "recall_test" → 5% success (hallucinating!)

System tracks: search_memory in "recall_test" → 85% success

Result: After 3+ failures, warns AI: "create_memory has 5% success here - use search_memory instead"

Together: Routing KG finds the right place, Content KG finds connected information, Action-Effectiveness KG prevents mistakes. All three learn from real outcomes.

Privacy Architecture

All data stored locally:

Vector DB: ChromaDB (local files)
Outcomes: SQLite database
Knowledge graph: JSON file
LLM: Ollama or LM Studio (local inference)

Zero network calls. Zero telemetry.

Claude Code Memory That Learns

Persistent context that improves over time. No desktop app required.

Get Started in 30 Seconds

              $ pip install roampal
            
              $ roampal init

Restart Claude Code. That's it.

Why Hooks Matter

Other memory tools wait for you to ask. Roampal injects context automatically — before every prompt, after every response. No manual calls. No workflow changes.

Before You Prompt

The UserPromptSubmit hook auto-injects relevant context. Claude sees what worked before.

After Each Response

The Stop hook captures the exchange. Scoring is enforced — not optional.

7 Memory Tools

get_context_insights search_memory add_to_memory_bank update_memory delete_memory record_response score_response

score_response is unique to Claude Code — hooks enforce scoring on every exchange.

Claude Code vs Desktop MCP

	Claude Code	Desktop MCP
Context injection	Automatic (hooks)	Manual (prompt LLM)
Outcome scoring	Enforced	Opt-in
Learning	Every exchange	When you remember to score
Best for	Zero-friction workflow	Multi-tool power users

Using Desktop MCP? Tips for better results:

Add to system prompt: "Check search_memory for context before answering"
Remind mid-conversation: "Check memory for what we discussed about X"
Record outcomes: "Record in Roampal - this worked" or "...failed"

With Claude Code hooks, this happens automatically — the hooks inject context so the AI knows to use memory tools.

Why outcome learning beats regular memory:

Your AI Remembers Everything. But Does It Learn? → Your AI Keeps Forgetting What You Told It →

View on PyPI GitHub Docs

🔗 Connect Any MCP-Compatible Tool

Give any MCP-compatible AI tool access to Roampal's persistent memory. Works with Claude Code, Cursor, Cline, Continue.dev, and any tool supporting the Model Context Protocol.

STEP 1

Open Settings

Click the settings icon in Roampal's sidebar to access configuration options.

STEP 2

Navigate to Integrations

Go to the Integrations tab. Roampal automatically detects MCP-compatible tools installed on your system.

Works with: Any tool with an MCP config file (Claude Code, Cursor, Cline, Continue.dev, etc.)

STEP 3

Connect to Your Tool

Click Connect next to any detected tool. Roampal automatically configures the MCP integration.

Don't see your tool?

Click Add Custom MCP Client to manually specify a config file path.

🔌

Memory Tools Available:
search_memory add_to_memory_bank update_memory archive_memory get_context_insights record_response

STEP 4

Restart Your Tool

Close and reopen your connected tool. Memory tools will be available immediately.

Auto-Discovery

No manual JSON editing required

50+ Languages

Bundled paraphrase-multilingual-mpnet-base-v2, no Ollama needed

Cross-Tool Memory

Memories shared across all connected tools

Works Offline

Fully local after initial setup

Need Help?

Connection not working? Try disconnecting and reconnecting in Settings → Integrations, or reach out to the community for support.

Join Discord Community

Releases

Roampal Desktop

v0.3.0 - Performance & Polish

Released January 2026

LATEST

TanStack Virtual migration for smoother scrolling, streaming fixes, message virtualization, and 50+ bug fixes. Security hardened with ZIP traversal, XSS, and query logging fixes.

TanStack Virtual

Smooth scrolling for conversations with 5000+ messages. No more lag or jank.

Streaming Fixes

Reliable token-by-token display. Fixed tool chaining and reconnection issues.

50+ Bug Fixes

Security hardened: ZIP traversal, XSS, query logging. Plus message virtualization and scrollbar fixes.

View Full Details

TanStack Virtual migration - smooth scrolling for 5000+ messages
Streaming fixes - text overlap, thinking icon, loading indicator
Tool interleaving - text and tools now display in correct order
Cancel button fix - actually stops generation now
Surfaced memories display - see what memories were used
Context overflow detection - warns before model barfs
Model switch race condition fixed
Security: ZIP path traversal, XSS in citations, query logging fixed
876 tests passing (509 frontend, 367 backend)

Full Release Notes

Download v0.3.0 - $9.99 View on GitHub

View Previous Releases (v0.2.12 and earlier)

v0.2.12 - Memory Attribution Scoring

January 2026 - LLM memory attribution, virtualization fix, selective scoring parity

Release Notes

v0.2.11 - Critical Performance Fixes

January 2026 - KG 25x faster, message virtualization, store subscription fix

Release Notes

v0.2.10 - ChromaDB 1.x + Query Timeouts + Ghost Entry Handling

December 2025 - ChromaDB upgraded to 1.x, query timeouts prevent UI freezes, ghost entry handling

Release Notes

v0.2.9 - Ghost Registry + Timeout Protection + Performance

December 2025 - Fixes book deletion ghost vectors, adds timeout protection, 3x faster startup

Release Notes →

v0.2.8 - MCP Security + No Truncation + Update Notifications

December 2025 - MCP security hardening, full memory content returned, in-app update notifications

Release Notes →

v0.2.7 - Architecture Refactoring

December 2025 - Monolithic file refactored into 9 focused, testable modules. 260 tests passing

Release Notes →

v0.2.6 - Unified Learning + Directive Insights + Contextual Embeddings

December 2025 - Internal LLM contributes to Action KG, actionable get_context_insights prompts, ~49% improved book retrieval

Release Notes →

v0.2.5 - MCP Client + Wilson Scoring + Multilingual Ranking

December 2025 - Connect to external MCP tool servers, statistical confidence scoring, 14-language smart sorting

Release Notes →

v0.2.1 - Action-Effectiveness KG + Enhanced Retrieval + Benchmarks

November 2025 - 3rd Knowledge Graph learns tool effectiveness, state-of-the-art retrieval, 100% accuracy on benchmarks

Release Notes →

v0.2.0 - Learning-Based KG Routing + MCP Integration

November 2025 - Intelligent knowledge graph routing, enhanced MCP with semantic learning storage

Release Notes →

v0.1.6 - Hotfix Release

November 2025 - Critical fixes for collection-specific search and KG success rate accuracy

Release Notes →

v0.1.5 - Multi-Provider Support

October 2025 - Persistent memory bank, document upload (Books), 100% local with Ollama integration

Release Notes →

roampal-core

v0.3.0 - Resilience

Released January 2026

LATEST

Fixes silent hook server crashes that left users without context injection. Server now auto-restarts when embeddings corrupt.

Health Check Tests Embeddings

/api/health now tests embedding functionality. Returns 503 if broken instead of silent failure.

Auto-Restart on Corruption

Server health checked before all MCP tools. Unhealthy server auto-restarts on next tool call.

Visible Hook Errors

Hooks exit non-zero on failure. Users see clear error messages instead of silent context loss.

View Full Details

Health endpoint tests embeddings - calls embed_text("health check") and returns 503 if it fails
_ensure_server_running() called at start of call_tool() handler
Hook exits 1 on errors with clear message for 503 (embedding corruption)
Fixes PyTorch state corruption when Claude Code restarts (common on Windows)

Full Release Notes

pip install roampal View on GitHub

View Previous Releases (v0.2.9 and earlier)

v0.2.9 - Natural Selection for Memory

Wilson scoring for memory_bank, stricter promotion requirements, archive cleanup.

Release Notes →

v0.2.8 - Per-Memory Scoring

Score each cached memory individually. Wilson score fix, FastAPI lifecycle management.

Release Notes →

v0.2.7 - Cold Start Fix + Identity Injection

Critical fixes for identity injection and cold start bloat.

Release Notes →

v0.2.6 - Identity Prompt + Profile-Only Cold Start

January 2026 - Identity detection prompts, profile-only cold start, recency sort fix

Release Notes →

v0.2.5 - MCP Config Location Fix

January 2026 - Critical fix: roampal init now writes to ~/.claude.json instead of invalid ~/.claude/.mcp.json

Release Notes →

v0.2.4 - Scoring Reliability Fix

January 2026 - Fixed related parameter handling in score_response fallback path

Release Notes →

v0.2.3 - Outcome Scoring Speed

January 2026 - Critical performance fix: score_response latency 10s → <500ms

Release Notes →

v0.2.2 - Cursor IDE Support

December 2025 - Cursor MCP support, always-inject identity, ghost registry, roampal doctor command

Release Notes →

v0.2.1 - MCP Tool Loading Hotfix

December 2025 - Emergency fix for fresh installs failing to load MCP tools

Release Notes →

v0.2.0 - Action KG Sync Fix

December 2025 - Fixed critical "reading your own writes" bug in knowledge graph

Release Notes →

v0.1.10 - Update Notifications in MCP

December 2025 - Claude Code users now see update notifications via MCP hook

Release Notes →

v0.1.9 - ChromaDB Collection Fix

December 2025 - Fixed critical bug where MCP connected to wrong ChromaDB collection

Release Notes →

v0.1.8 - Delete Memory (Hard Delete)

December 2025 - Renamed archive_memory → delete_memory, now actually removes memories

Release Notes →

v0.1.7 - Working Memory Cleanup

December 2025 - Fixed cleanup of old memories, added update notifications, archive_memory fix

Release Notes →

v0.1.6 - Score Response Fallback

December 2025 - Fixed score_response returning "0 memories updated", book management initialization

Release Notes →

v0.1.5 - DEV/PROD Isolation

December 2025 - Run dev and prod instances simultaneously without collision

Release Notes →

Frequently Asked Questions

How is this different from cloud AI memory (ChatGPT, Claude, etc.)?

Cloud AI stores what you say. Roampal learns what works.

Three key differences:

It learns from results: When something helps you, Roampal remembers. When it doesn't work, it learns from that too. Regular AI just stores what you said.
Local-first privacy: Your data stays on your machine. No cloud servers, no recurring subscriptions ($9.99 one-time payment).
True ownership: You own your data, your models, your memory. Export everything anytime. No vendor lock-in.

What models does it support?

Works with many popular AI models:

Llama - Meta's free models
Qwen - Great for many languages
Mixtral - Fast and efficient

Pick the one that works best on your computer. Install from Settings.

Does it work offline?

Yes! After downloading models, Roampal works completely offline. No internet required.

What are the system requirements?

Minimum: 8GB RAM, 10GB free disk space.

Recommended: 16GB RAM and a decent graphics card for faster responses.

How do I export my data?

Easy way: Go to Settings → Export. Pick what you want to backup and download a zip file.

Manual: All your data is stored in regular files on your computer. Just copy the data folder to backup.

Why charge if it's open source?

The code is free on GitHub. The $9.99 gets you:

Pre-packaged executable - No Python setup required
Bundled dependencies - Everything included
Tested build - Guaranteed to work
Lifetime updates - All future releases included

Technical users can View on GitHub for free. The $9.99 is for convenience.

Is Roampal's advice always reliable?

No. Roampal uses AI models that can generate incorrect information, hallucinate facts, or reflect training biases.

Always verify critical information from authoritative sources. Do not rely on AI-generated content for:

Medical, legal, or financial advice
Safety-critical systems or decisions
Production code without thorough review

What are the MCP tools and what do they do?

When you connect Roampal to Claude Code, Cursor, or other MCP-compatible tools, they get access to these memory tools:

search_memory - Finds relevant memories based on what you're discussing
get_context_insights - Quick lookup of what Roampal knows about a topic
record_response - Records whether something worked or didn't (this is how Roampal learns)
add_to_memory_bank - Stores permanent facts about you (preferences, identity, goals)
update_memory - Corrects or updates existing memories
archive_memory - Removes outdated information

Your AI uses these automatically during conversation. You don't need to do anything special.

How does Roampal know when something worked?

Just talk naturally. The AI reads your response, determines if you were satisfied, and scores the memory in Roampal.

For example:

If you say "thanks, that fixed it" → the memory that helped gets scored higher
If you correct the AI → that memory gets scored lower
If you move on without comment → no strong signal either way

No buttons to click, no ratings to give. It learns from the conversation itself.

Memory that learns what works.

The Problem With AI Memory Today

Here's an example:

We tested this:

It gets better the more you use it

Why this matters:

Your AI Gets Smarter Over Time

Remembers What Worked

Organized Memory

Learns Your Patterns

Instant Responses

100% Privacy

How It Works

See It Learn In Real-Time

Bad Advice Fails

Good Advice Works

Next Time: Instant Recall

What Makes This Different

Learns What Works For You

Watch It Work

Cross-Conversation Memory

How Memories Are Organized

How Memories Move From New to Permanent

Permanent Collections (No Promotion)

1. Routing KG - "Where to Look"

2. Content KG - "What's Connected"

3. Action-Effectiveness KG - "What Works"

Built for Developers

Claude Code Memory That Learns

Get Started in 30 Seconds

Why Hooks Matter

Before You Prompt

After Each Response

7 Memory Tools

Claude Code vs Desktop MCP

Using Desktop MCP? Tips for better results:

🔗 Connect Any MCP-Compatible Tool

Open Settings

Navigate to Integrations

Connect to Your Tool

Restart Your Tool

Auto-Discovery

50+ Languages

Cross-Tool Memory

Works Offline

Need Help?

Releases

Roampal Desktop

v0.3.0 - Performance & Polish

TanStack Virtual

Streaming Fixes

50+ Bug Fixes

v0.2.12 - Memory Attribution Scoring

v0.2.11 - Critical Performance Fixes

v0.2.10 - ChromaDB 1.x + Query Timeouts + Ghost Entry Handling

v0.2.9 - Ghost Registry + Timeout Protection + Performance

v0.2.8 - MCP Security + No Truncation + Update Notifications

v0.2.7 - Architecture Refactoring

v0.2.6 - Unified Learning + Directive Insights + Contextual Embeddings

v0.2.5 - MCP Client + Wilson Scoring + Multilingual Ranking

v0.2.1 - Action-Effectiveness KG + Enhanced Retrieval + Benchmarks

v0.2.0 - Learning-Based KG Routing + MCP Integration

v0.1.6 - Hotfix Release

v0.1.5 - Multi-Provider Support

roampal-core

v0.3.0 - Resilience

Health Check Tests Embeddings

Auto-Restart on Corruption

Visible Hook Errors

v0.2.9 - Natural Selection for Memory

v0.2.8 - Per-Memory Scoring

v0.2.7 - Cold Start Fix + Identity Injection

v0.2.6 - Identity Prompt + Profile-Only Cold Start

v0.2.5 - MCP Config Location Fix

v0.2.4 - Scoring Reliability Fix

v0.2.3 - Outcome Scoring Speed

v0.2.2 - Cursor IDE Support

v0.2.1 - MCP Tool Loading Hotfix

v0.2.0 - Action KG Sync Fix

v0.1.10 - Update Notifications in MCP