{"id":45403468,"url":"https://github.com/adrianwedd/rlm-mcp","last_synced_at":"2026-02-21T20:36:30.666Z","repository":{"id":332535009,"uuid":"1134062092","full_name":"adrianwedd/rlm-mcp","owner":"adrianwedd","description":"MCP server implementing Recursive Language Model pattern for processing arbitrarily long contexts. Enables Claude Code to work with 1M+ character documents through session-based chunking, BM25 search, and artifact provenance tracking.","archived":false,"fork":false,"pushed_at":"2026-01-14T12:47:56.000Z","size":164,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-14T13:39:58.791Z","etag":null,"topics":["bm25-search","claude","claude-code","context-window","document-processing","fastmcp","llm","mcp","model-context-protocol","recursive-language-model"],"latest_commit_sha":null,"homepage":"https://modelcontextprotocol.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adrianwedd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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":"2026-01-14T07:37:44.000Z","updated_at":"2026-01-14T12:48:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/adrianwedd/rlm-mcp","commit_stats":null,"previous_names":["adrianwedd/rlm-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/adrianwedd/rlm-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrianwedd%2Frlm-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrianwedd%2Frlm-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrianwedd%2Frlm-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrianwedd%2Frlm-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adrianwedd","download_url":"https://codeload.github.com/adrianwedd/rlm-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrianwedd%2Frlm-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29692521,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T18:18:25.093Z","status":"ssl_error","status_checked_at":"2026-02-21T18:18:22.435Z","response_time":107,"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":["bm25-search","claude","claude-code","context-window","document-processing","fastmcp","llm","mcp","model-context-protocol","recursive-language-model"],"created_at":"2026-02-21T20:36:29.948Z","updated_at":"2026-02-21T20:36:30.656Z","avatar_url":"https://github.com/adrianwedd.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RLM-MCP: Recursive Language Model Server for Claude Code\n\n**Status**: ✅ v0.2.2 - Production-Ready for Team Environments\n\nA Model Context Protocol (MCP) server implementing the Recursive Language Model pattern from [Zhang et al. (2025)](https://arxiv.org/abs/2512.24601), enabling LLMs to process arbitrarily long contexts by treating prompts as external environment objects.\n\n**What's New in v0.2.x**:\n- **v0.2.2**: Exact BM25 doc_ids filtering • Highlight bounds clamping • Server config defaults • Budget exemption for session.close\n- **v0.2.1**: Atomic budget enforcement • chunk_index persistence • Truncation warnings • Error message improvements\n- **v0.2.0**: Persistent indexes • Concurrent session safety • Structured logging • Batch document loading (2-3x faster)\n\n## Key Insight\n\n\u003e Long prompts should not be fed into the neural network directly but should instead be treated as part of the environment that the LLM can symbolically interact with.\n\n## Features\n\n### Core Capabilities\n- **Session-based document management** — Load files, directories, or inline content with batch processing\n- **On-demand chunking** — Fixed, line-based, or delimiter-based strategies with intelligent caching\n- **BM25 search** — Lazy-built, persistently cached, survives server restarts\n- **Artifact storage** — Store derived results with complete span provenance\n\n### Production Features (v0.2.0)\n- **Persistent indexes** — BM25 indexes saved to disk with atomic writes and corruption recovery\n- **Concurrent session safety** — Per-session locks prevent race conditions in multi-user environments\n- **Structured logging** — JSON output with correlation IDs for production observability\n- **Batch document loading** — Concurrent file loading with memory-bounded semaphores (2-3x faster)\n\n## Status \u0026 Validation\n\n**v0.2.2** production-ready validation:\n\n- ✅ **103/103 tests passing** (100% functionality + production features)\n- ✅ **All 13 core tools** implemented with canonical naming\n- ✅ **MCP protocol integration** confirmed with real clients\n- ✅ **Large corpus tested** — 1M+ chars loaded and indexed\n- ✅ **Performance validated** — Sub-second searches, \u003c100ms index loads from disk\n- ✅ **Concurrency tested** — 50 concurrent operations, no race conditions\n- ✅ **Memory safety** — Bounded semaphores prevent OOM on large batches\n- ✅ **Production logging** — JSON structured logs with correlation tracking\n\n### Test Coverage\n- Error handling: 13 tests\n- Concurrency safety: 9 tests\n- Index persistence: 10 tests\n- Integration workflows: 14 tests\n- Large corpus performance: 5 tests\n- Structured logging: 13 tests\n- Batch loading: 7 tests\n- Provenance tracking: 8 tests\n- Storage layer: 11 tests\n- v0.2.2 bug fixes: 13 tests\n\nSee `MIGRATION_v0.1_to_v0.2.md` for upgrade guide.\n\n## Installation\n\n```bash\npip install rlm-mcp\n```\n\nOr with development dependencies:\n\n```bash\npip install rlm-mcp[dev]\n```\n\n## Quick Start\n\n```python\nfrom rlm_mcp import run_server\n\n# Start the MCP server\nrun_server()\n```\n\n## Tools\n\nAll tools use canonical naming: `rlm.\u003ccategory\u003e.\u003caction\u003e`\n\n| Category | Tools |\n|----------|-------|\n| `rlm.session` | `create`, `info`, `close` |\n| `rlm.docs` | `load`, `list`, `peek` |\n| `rlm.chunk` | `create` |\n| `rlm.span` | `get` |\n| `rlm.search` | `query` |\n| `rlm.artifact` | `store`, `list`, `get` |\n\n## Workflow Pattern\n\n1. **Initialize**: `rlm.session.create` with config\n2. **Load**: `rlm.docs.load` documents\n3. **Probe**: `rlm.docs.peek` at structure\n4. **Search**: `rlm.search.query` to find relevant sections\n5. **Chunk**: `rlm.chunk.create` with appropriate strategy\n6. **Process**: `rlm.span.get` + client subcalls\n7. **Store**: `rlm.artifact.store` results with provenance\n8. **Close**: `rlm.session.close`\n\n## Configuration\n\nConfiguration file: `~/.rlm-mcp/config.yaml`\n\n```yaml\n# Data storage\ndata_dir: ~/.rlm-mcp\n\n# Session limits (per-session overridable)\ndefault_max_tool_calls: 500\ndefault_max_chars_per_response: 50000\ndefault_max_chars_per_peek: 10000\n\n# Batch loading (v0.2.0)\nmax_concurrent_loads: 20   # Max concurrent file loads (memory safety)\nmax_file_size_mb: 100      # Reject files larger than this\n\n# Logging (v0.2.0)\nlog_level: \"INFO\"              # DEBUG, INFO, WARNING, ERROR\nstructured_logging: true       # JSON format (true) vs human-readable (false)\nlog_file: null                 # Optional: \"/var/log/rlm-mcp.log\"\n\n# Tool naming: strict by default (fails if SDK doesn't support canonical names)\n# Only set to true for experimentation with older MCP SDKs\nallow_noncanonical_tool_names: false\n```\n\n### Tool Naming (Strict vs Compat Mode)\n\nBy default, RLM-MCP requires an MCP SDK that supports explicit tool naming (e.g., FastMCP). This ensures tools are discoverable as `rlm.session.create`, not `rlm_session_create`.\n\n- **Strict mode (default)**: Server fails to start if SDK doesn't support `tool(name=...)`\n- **Compat mode**: Falls back to function names with a warning. Use only for experimentation.\n\n```yaml\n# ~/.rlm-mcp/config.yaml\nallow_noncanonical_tool_names: true  # Enable compat mode (not recommended)\n```\n\n## Logging (v0.2.0)\n\nRLM-MCP produces structured JSON logs for production observability. Each operation gets a unique correlation ID for tracing related events.\n\n### JSON Log Format\n\n```json\n{\n  \"timestamp\": \"2026-01-15T10:30:45.123456Z\",\n  \"level\": \"INFO\",\n  \"logger\": \"rlm_mcp.server\",\n  \"message\": \"Completed rlm.session.create\",\n  \"correlation_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"session_id\": \"session-123\",\n  \"operation\": \"rlm.session.create\",\n  \"duration_ms\": 42,\n  \"success\": true\n}\n```\n\n### Filtering Logs\n\n```bash\n# Filter by session\ncat /var/log/rlm-mcp.log | jq 'select(.session_id == \"session-123\")'\n\n# Filter by operation\ncat /var/log/rlm-mcp.log | jq 'select(.operation == \"rlm.search.query\")'\n\n# Track operation with correlation ID\ncat /var/log/rlm-mcp.log | jq 'select(.correlation_id == \"a1b2c3d4...\")'\n\n# Only errors\ncat /var/log/rlm-mcp.log | jq 'select(.level == \"ERROR\")'\n```\n\nSee `docs/LOGGING.md` for detailed logging guide.\n\n## Session Config\n\n```python\n{\n    \"max_tool_calls\": 500,           # Budget enforcement\n    \"max_chars_per_response\": 50000, # DOS protection\n    \"max_chars_per_peek\": 10000,     # DOS protection\n    \"chunk_cache_enabled\": True,\n    \"model_hints\": {                 # Advisory for client\n        \"root_model\": \"claude-opus-4-5-20251101\",\n        \"subcall_model\": \"claude-sonnet-4-5-20250929\",\n        \"bulk_model\": \"claude-haiku-4-5-20251001\"\n    }\n}\n```\n\n## Architecture\n\n```\n┌─────────────────────────────────────────┐\n│  Claude Skills (policy layer)           │\n├─────────────────────────────────────────┤\n│  MCP Server (RLM Runtime)               │\n│  • Session management + concurrency     │\n│  • Document/span operations             │\n│  • BM25 search (lazy, persisted)        │\n│  • Batch loading with semaphores        │\n│  • Response size caps                   │\n├─────────────────────────────────────────┤\n│  Local Persistence (v0.2.0)             │\n│  • SQLite: sessions, docs, spans        │\n│  • Blob store: content-addressed        │\n│  • Index cache: persistent BM25         │\n│  • Structured logs: JSON + correlation  │\n└─────────────────────────────────────────┘\n```\n\n## Design Principles\n\n1. **Local-first** — All reads/writes hit local storage\n2. **Client-managed subcalls** — MCP is the \"world\", client makes LLM calls\n3. **Immutable documents** — Content-addressed, never modified\n4. **On-demand chunking** — Chunk at query time, cache results\n5. **DOS protection** — Hard caps on response sizes\n\n## Development\n\n```bash\n# Clone and install with uv (recommended)\ngit clone https://github.com/yourorg/rlm-mcp.git\ncd rlm-mcp\nuv sync --extra dev\n\n# Run tests\nuv run pytest\n\n# Or with pip (editable install required for tests)\npip install -e \".[dev]\"\npytest\n\n# Type checking\nuv run mypy src/\n\n# Linting\nuv run ruff check src/\n```\n\n### Smoke Test with MCP Inspector\n\nTo validate tool discovery and schemas from a real client:\n\n```bash\n# Start server\nuv run rlm-mcp\n\n# In another terminal, use MCP Inspector\nnpx @anthropic/mcp-inspector\n```\n\nVerify:\n- Tool names appear as `rlm.session.create`, not `rlm_session_create`\n- Schemas match expected input/output structures\n- `truncated` and `index_built` fields appear in responses\n\n## License\n\nMIT\n\n## References\n\n- Zhang, A. L., Kraska, T., \u0026 Khattab, O. (2025). *Recursive Language Models*. arXiv:2512.24601\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadrianwedd%2Frlm-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadrianwedd%2Frlm-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadrianwedd%2Frlm-mcp/lists"}