{"id":45750101,"url":"https://github.com/roampal-ai/roampal-core","last_synced_at":"2026-04-15T00:05:00.515Z","repository":{"id":328877025,"uuid":"1117163740","full_name":"roampal-ai/roampal-core","owner":"roampal-ai","description":"Outcome-based persistent memory MCP server for Claude Code and OpenCode. Good advice promoted, bad advice demoted. pip install roampal.","archived":false,"fork":false,"pushed_at":"2026-04-09T19:22:25.000Z","size":1368,"stargazers_count":40,"open_issues_count":0,"forks_count":5,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-09T21:16:45.837Z","etag":null,"topics":["agent-memory","ai-assistant","ai-coding","ai-coding-assistant","ai-memory","ai-tools","chromadb","claude-code","coding-assistant","developer-tools","llm","long-term-memory","mcp","mcp-server","memory","model-context-protocol","opencode","persistent-memory","python","semantic-search"],"latest_commit_sha":null,"homepage":"https://roampal.ai","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/roampal-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-15T23:26:55.000Z","updated_at":"2026-04-09T19:12:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/roampal-ai/roampal-core","commit_stats":null,"previous_names":["roampal-ai/roampal-core"],"tags_count":48,"template":false,"template_full_name":null,"purl":"pkg:github/roampal-ai/roampal-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roampal-ai%2Froampal-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roampal-ai%2Froampal-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roampal-ai%2Froampal-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roampal-ai%2Froampal-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roampal-ai","download_url":"https://codeload.github.com/roampal-ai/roampal-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roampal-ai%2Froampal-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31820370,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"ssl_error","status_checked_at":"2026-04-14T18:05:01.765Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","ai-assistant","ai-coding","ai-coding-assistant","ai-memory","ai-tools","chromadb","claude-code","coding-assistant","developer-tools","llm","long-term-memory","mcp","mcp-server","memory","model-context-protocol","opencode","persistent-memory","python","semantic-search"],"created_at":"2026-02-25T18:07:37.900Z","updated_at":"2026-04-15T00:05:00.506Z","avatar_url":"https://github.com/roampal-ai.png","language":"Python","funding_links":[],"categories":["Memory \u0026 Context Persistence"],"sub_categories":[],"readme":"# Roampal — Outcome-Based Persistent Memory MCP Server\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/roampal-ai/roampal-core/actions/workflows/tests.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/roampal-ai/roampal-core/tests.yml?branch=main\u0026style=flat-square\u0026label=tests\" alt=\"Tests\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/roampal/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/roampal?color=blue\u0026style=flat-square\" alt=\"PyPI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/roampal/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/dm/roampal?color=blue\u0026style=flat-square\" alt=\"Downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/roampal-ai/roampal-core/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/roampal-ai/roampal-core?color=blue\u0026style=flat-square\" alt=\"Stars\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/roampal-ai/roampal-core/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.python.org/downloads/\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.10+-blue?style=flat-square\" alt=\"Python\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://discord.com/invite/F87za86R3v\"\u003e\u003cimg src=\"https://img.shields.io/badge/discord-join-blue?style=flat-square\" alt=\"Discord\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://glama.ai/mcp/servers/roampal-ai/roampal-core\"\u003e\u003cimg src=\"https://glama.ai/mcp/servers/roampal-ai/roampal-core/badges/card.svg\" alt=\"roampal-core MCP server\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eTwo commands. Your AI coding assistant gets outcome-based memory.\u003c/strong\u003e\u003cbr\u003e\n  Works with \u003cstrong\u003eClaude Code\u003c/strong\u003e and \u003cstrong\u003eOpenCode\u003c/strong\u003e.\n\u003c/p\u003e\n\n---\n\n## Why?\n\nAI coding assistants forget everything between sessions. You explain your architecture, your preferences, your conventions — again. When they give bad advice, there's no mechanism to learn from it.\n\nRoampal is an MCP server that gives your AI persistent, outcome-based memory across every session. Good advice gets promoted. Bad advice gets demoted. Your AI learns what works and what doesn't — automatically, with zero workflow changes.\n\n### Benchmarks\n\n**85.8% on LoCoMo** (non-adversarial, end-to-end answer accuracy) — validated on 1,986 questions across 10 conversations with dual grading.\n\n| Result | Score |\n|--------|-------|\n| Conversational learning vs raw ingestion | **+23 points** (76.6% vs 53.0%, p\u003c0.0001) |\n| Architecture vs model effect | Architecture **~10x larger** contributor |\n| Poison resilience (1,135 adversarial memories) | **-2.6 to -4.2 points** only |\n| TagCascade retrieval (tags-first + CE rerank) | **+1.9 Hit@1** vs pure CE (p\u003c0.0001) |\n\nBenchmark pipeline runs on a single GPU with no cloud dependencies. Roampal itself runs on CPU — no GPU required. Full methodology, data, and evaluation scripts: [roampal-labs](https://github.com/roampal-ai/roampal-labs)\n\nPaper: *\"Beyond Ingestion: What Conversational Memory Learning Reveals on a Corrected LoCoMo Benchmark\"* (Logan Teague, April 2026)\n\n---\n\n## Quick Start\n\n```bash\npip install roampal\nroampal init\n```\n\nAuto-detects installed tools. Restart your editor and start chatting.\n\n\u003e Target a specific tool: `roampal init --claude-code` or `roampal init --opencode`\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/init-demo.svg\" alt=\"roampal init demo\" width=\"720\"\u003e\n\u003c/p\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003ePlatform Differences\u003c/strong\u003e\u003c/summary\u003e\n\nThe core loop is identical — both platforms inject context, capture exchanges, and score outcomes. The delivery mechanism differs:\n\n| | Claude Code | OpenCode |\n|--|-------------|----------|\n| Context injection | Hooks (stdout) | Plugin (system prompt) |\n| Exchange capture | Stop hook | Plugin `session.idle` event |\n| Scoring | Main LLM via `score_memories` tool | Independent sidecar (your chosen model \u003e Zen free) |\n| Self-healing | Hooks auto-restart server on failure | Plugin auto-restarts server on failure |\n\nClaude Code prompts the main LLM to score each exchange via the `score_memories` tool. OpenCode never self-scores — an independent sidecar (a separate API call) reviews each exchange as a third party, removing self-assessment bias. The `score_memories` tool is not registered on OpenCode. During `roampal init` or `roampal sidecar setup`, Roampal detects local models (Ollama, LM Studio, etc.) and lets you choose a scoring model. If configured, these take priority (Zen is skipped for privacy). A cheap or local model works great — scoring doesn't need a powerful model. Defaults to Zen free models (remote, best-effort) if you skip setup.\n\u003c/details\u003e\n\n## How It Works\n\nWhen you type a message, Roampal automatically injects relevant context before your AI sees it:\n\n**You type:**\n```\nfix the auth bug\n```\n\n**Your AI sees:**\n```\n═══ KNOWN CONTEXT ═══\n• JWT refresh pattern fixed auth loop [id:patterns_a1b2] (3d, 90% proven, patterns)\n• User prefers: never stage git changes [id:mb_c3d4] (memory_bank)\n═══ END CONTEXT ═══\n\nfix the auth bug\n```\n\nNo manual calls. No workflow changes. It just works.\n\n### The Loop\n\n1. **You type** a message\n2. **Roampal injects** relevant context automatically (hooks in Claude Code, plugin in OpenCode)\n3. **AI responds** with full awareness of your history, preferences, and what worked before\n4. **Outcome scored** — good advice gets promoted, bad advice gets demoted\n5. **Repeat** — the system gets smarter every exchange\n\n### Five Memory Collections\n\n| Collection | Purpose | Lifetime |\n|------------|---------|----------|\n| `working` | Current session context | 24h — promotes if useful, deleted otherwise |\n| `history` | Past conversations | 30 days, outcome-scored |\n| `patterns` | Proven solutions | Persistent while useful, promoted from history |\n| `memory_bank` | Identity, preferences, goals | Permanent |\n| `books` | Uploaded reference docs | Permanent |\n\n## Commands\n\n```bash\nroampal init                # Auto-detect and configure installed tools\nroampal init --claude-code  # Configure Claude Code explicitly\nroampal init --opencode     # Configure OpenCode explicitly\nroampal init --no-input     # Non-interactive setup (CI/scripts)\nroampal start               # Start the HTTP server manually\nroampal stop                # Stop the HTTP server\nroampal status              # Check if server is running\nroampal status --json       # Machine-readable status (for scripting)\nroampal stats               # View memory statistics\nroampal stats --json        # Machine-readable statistics (for scripting)\nroampal doctor              # Diagnose installation issues\nroampal summarize           # Summarize long memories (retroactive cleanup)\nroampal score               # Score the last exchange (manual/testing)\nroampal context             # Output recent exchange context\nroampal ingest \u003cfile\u003e       # Add documents to books collection\nroampal books               # List all ingested books\nroampal remove \u003ctitle\u003e      # Remove a book by title\nroampal sidecar status      # Check scoring model configuration (OpenCode)\nroampal sidecar setup       # Configure scoring model (OpenCode)\nroampal sidecar test        # Test scoring model response format (OpenCode)\nroampal retag               # Re-extract tags on memories using sidecar LLM\nroampal sidecar disable     # Remove scoring model configuration (OpenCode)\n```\n\n## MCP Tools\n\nYour AI gets these memory tools:\n\n| Tool | Description | Platforms |\n|------|-------------|-----------|\n| `search_memory` | Deep search across all collections | Both |\n| `add_to_memory_bank` | Store permanent facts (identity, preferences, goals) | Both |\n| `update_memory` | Correct or update existing memories | Both |\n| `delete_memory` | Remove outdated info | Both |\n| `score_memories` | Score previous exchange outcomes | Claude Code |\n| `record_response` | Store key takeaways from significant exchanges | Both |\n\n\u003e **How scoring works:** Claude Code's hooks prompt the main LLM to call `score_memories` every turn. OpenCode uses an independent sidecar that scores silently in the background — the model never sees a scoring prompt and `score_memories` is not registered as a tool. If the sidecar is unavailable, a warning prompts the user to run `roampal sidecar setup`. Choose your scoring model during `roampal init` or via `roampal sidecar setup`.\n\n## How Roampal Compares\n\n| Feature | Roampal Core | Claude Code built-in (CLAUDE.md / auto memory) | OpenCode built-in |\n|---------|-------------|--------------------------------------------------|-------------------|\n| Learns from outcomes | Yes — bad advice demoted, good advice promoted | No | No |\n| Semantic retrieval | Yes — TagCascade + cross-encoder reranking | No — files loaded in full, no search | No memory system |\n| Context injection | Automatic — relevant memories per query | Full CLAUDE.md every session, auto memory on demand | None |\n| Atomic fact extraction | Yes — summaries + facts, two-lane retrieval | No — saves what Claude decides is useful | No |\n| Works across projects | Yes — shared memory across all projects | Per-project only (per git repo) | No memory |\n| Scales with history | Yes — 5 collections, promotion/demotion/decay | CLAUDE.md unbounded, auto memory first 200 lines | No memory |\n| Fully local / private | Yes — ChromaDB on your machine | Yes | Yes |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eArchitecture\u003c/strong\u003e\u003c/summary\u003e\n\n```\n┌─────────────────────────────────────────────────────────┐\n│  pip install roampal \u0026\u0026 roampal init                    │\n│    Claude Code: hooks + MCP → ~/.claude/                │\n│    OpenCode:    plugin + MCP → ~/.config/opencode/      │\n└─────────────────────────────────────────────────────────┘\n                         │\n                         ▼\n┌─────────────────────────────────────────────────────────┐\n│  HTTP Hook Server (port 27182)                          │\n│    Auto-started on first use, self-heals on failure     │\n│    Manual control: roampal start / roampal stop         │\n└─────────────────────────────────────────────────────────┘\n                         │\n                         ▼\n┌─────────────────────────────────────────────────────────┐\n│  User types message                                     │\n│    → Hook/plugin calls HTTP server for context          │\n│    → AI sees relevant memories, responds                │\n│    → Exchange stored, scored (hooks or sidecar)         │\n└─────────────────────────────────────────────────────────┘\n                         │\n                         ▼\n┌─────────────────────────────────────────────────────────┐\n│  Single-Writer Backend                                  │\n│    FastAPI → UnifiedMemorySystem → ChromaDB             │\n│    All clients share one server, isolated by session    │\n└─────────────────────────────────────────────────────────┘\n```\n\nSee [`dev/docs/`](dev/docs/) for full technical details.\n\u003c/details\u003e\n\n## Requirements\n\n- Python 3.10+\n- One of: **Claude Code** or **OpenCode**\n- **Platforms:** Windows, macOS, Linux (primarily developed and tested on Windows)\n- **RAM:** ~800MB available (cross-encoder reranker + embeddings + ChromaDB)\n- **Disk:** ~500MB for models (multilingual embedding + reranker, downloaded automatically on first use)\n- **CPU:** Any modern x86-64 processor with AVX2 (Intel Haswell 2013+ / AMD Excavator 2015+)\n- **GPU:** Not required — all inference runs on CPU via ONNX Runtime\n\n## Troubleshooting\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHooks not working? (Claude Code)\u003c/strong\u003e\u003c/summary\u003e\n\n- Restart Claude Code (hooks load on startup)\n- Check HTTP server: `curl http://127.0.0.1:27182/api/health`\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eMCP not connecting? (Claude Code)\u003c/strong\u003e\u003c/summary\u003e\n\n- Verify `~/.claude.json` has the `roampal-core` MCP entry with correct Python path\n- Check Claude Code output panel for MCP errors\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eContext not appearing? (OpenCode)\u003c/strong\u003e\u003c/summary\u003e\n\n- Make sure you ran `roampal init --opencode`\n- Check that the server auto-started: `curl http://127.0.0.1:27182/api/health`\n- If not, start it manually: `roampal start`\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eServer crashes and recovers?\u003c/strong\u003e\u003c/summary\u003e\n\nThis is expected. Roampal has self-healing -- if the HTTP server stops responding, it is automatically restarted and retried.\n\u003c/details\u003e\n\n**Still stuck?** Ask your AI for help — it can read logs and debug Roampal issues directly.\n\n## Support\n\nRoampal Core is completely free and open source.\n\n- Support development: [roampal.gumroad.com](https://roampal.gumroad.com/l/aagzxv)\n- Feature ideas \u0026 feedback: [Discord](https://discord.com/invite/F87za86R3v)\n- Bug reports: [GitHub Issues](https://github.com/roampal-ai/roampal-core/issues)\n- Need help with AI memory? Reach out: **roampal@protonmail.com** | [LinkedIn](https://www.linkedin.com/in/logan-teague-6909901a5/)\n\n## License\n\n[Apache 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froampal-ai%2Froampal-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froampal-ai%2Froampal-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froampal-ai%2Froampal-core/lists"}