ResearchGravity MCP server
Commit Oct 25, 2026An AI research framework that captures, stores, and analyzes intelligence through multi-tier signal capture and graph-based knowledge management.
Also known as Dicoangelo/ResearchGravity
- Stars
- 4
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 25, 2026
- License
- MIT
What is ResearchGravity MCP?
ResearchGravity is an AI research framework that captures, stores, and analyzes intelligence through multi-tier signal capture and graph-based knowledge management.
Summary generated from the project's README
About ResearchGravity MCP server
Researchers and developers looking to build a sovereign knowledge base can use ResearchGravity to capture, store, and analyze intelligence through a multi-tier signal capture system. The framework functions as an AI second brain, utilizing a graph-based management system to track relationships between sessions, findings, and papers. It supports local deployment with SQLite and sqlite-vec for offline vector storage, or can integrate with Qdrant for full semantic search capabilities.
Users interact with the system via an interactive REPL, a command-line interface, or a REST API. The platform includes an auto-capture feature that extracts URLs and findings from Claude sessions and a file watcher daemon that creates sessions from background activity. To ensure high-quality outputs, the system employs a writer-critic architecture and an oracle consensus mechanism to validate archives and evidence. Security is managed through JWT authentication and rate limiting on API endpoints.
What you can do with it
- 1Automated research session loggingAn AI client can automatically extract URLs and key findings from active research sessions to build a knowledge graph.
- 2Predicting research session qualityA developer can use the intelligence layer to predict the quality or likely errors of a specific research task.
- 3Semantic knowledge retrievalUsers can perform semantic searches across past research sessions using vector storage.
- 4Validating research findingsThe system uses multiple critics to validate the evidence and context of captured research data.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
COHERE_API_KEYRG_API_KEYRG_LOG_JSONRG_LOG_LEVELRG_SECRET_KEY
| Name | Description | |
|---|---|---|
| COHERE_API_KEY | — | |
| RG_API_KEY | — | |
| RG_LOG_JSON | — | |
| RG_LOG_LEVEL | — | |
| RG_SECRET_KEY | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabledicoangelo/researchgravity is public and reachablegithub.com/dicoangelo/researchgravity ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-25github.com/dicoangelo/researchgravity ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubWhy • What's New • Architecture • Quick Start • Auto-Capture • Sources • Contact
Proof Deck — See It Work
New local pilot: BASIX × ResearchGravity compares a bounded image-upscale workload, records source-backed decisions, and exports a selected handoff. Includes CLI, loopback UI, MCP tools and isolated SQLite indexing. See its validation and limits.
What's New in v6.1 — Security & Reliability (January 2026)
Production-hardened API with enterprise security.
| Feature | Description |
|---|---|
| 🔐 JWT Authentication | Token-based auth with /api/auth/token endpoint |
| ⏱️ Rate Limiting | slowapi integration (10/min search, 30/min write) |
| 🛡️ Input Validation | Path traversal prevention, session ID sanitization |
| 📝 Structured Logging | JSON/console formats with request context |
| 🔄 Dead-Letter Queue | Failed writes queued for retry with exponential backoff |
| ⚡ Async Cohere | Non-blocking embedding calls via asyncio.to_thread |
| 🔒 Connection Pool | Semaphore-guarded SQLite pool (race condition fix) |
Authentication
# Get JWT token
curl -X POST http://localhost:3847/api/auth/token \
-H "Content-Type: application/json" \
-d '{"client_id": "my-app", "scope": "write"}'
# Use token
curl -H "Authorization: Bearer <token>" http://localhost:3847/api/auth/me
# Or use API key
curl -H "X-API-Key: <your-api-key>" http://localhost:3847/api/v2/stats
Environment Variables
export RG_SECRET_KEY=$(python -c "import secrets; print(secrets.token_hex(32))")
export RG_API_KEY="your-service-api-key"
export RG_LOG_LEVEL="INFO" # DEBUG, INFO, WARNING, ERROR
export RG_LOG_JSON="true" # JSON format for production
What's New in v6.0 — Interactive Research Platform (January 2026)
From manual workflow to intelligent auto-capture. 3x faster research sessions with real-time URL capture.
| Feature | Description |
|---|---|
| 🎮 Interactive REPL | Real-time research CLI with Rich terminal UI |
| 🔄 Auto-Capture V2 | Automatic URL/finding extraction from Claude sessions (+70% capture rate) |
| 🧠 Intelligence Layer | CLI + API + REPL access to meta-learning predictions |
| 💾 sqlite-vec Storage | Local vector storage with FTS fallback (no external dependencies) |
| 👁️ File Watcher | Implicit session creation from Claude activity |
| 📊 Dual-Write Engine | Qdrant + sqlite-vec with automatic failover |
Interactive REPL
python3 scripts/session/repl.py
# Commands:
rg> start "multi-agent orchestration" # Initialize session
rg> url https://arxiv.org/... # Log URL (auto-classify)
rg> finding "Key insight about..." # Capture finding
rg> predict # Session quality prediction
rg> search "consensus algorithms" # Semantic search past sessions
rg> archive # Finalize session
Auto-Capture V2
python3 scripts/session/auto_capture_v2.py scan # Scan last 24 hours
python3 scripts/session/auto_capture_v2.py scan --hours 48
python3 scripts/session/auto_capture_v2.py status # Show capture stats
Intelligence CLI
python3 scripts/prediction/intelligence.py predict "task" # Session quality prediction
python3 scripts/prediction/intelligence.py optimal-time # Best hour for deep work
python3 scripts/prediction/intelligence.py errors "context" # Likely errors + prevention
python3 scripts/prediction/intelligence.py patterns # Session patterns
Intelligence API
| Endpoint | Method | Description |
|---|---|---|
/api/v2/intelligence/status |
GET | System capabilities |
/api/v2/intelligence/predict |
POST | Unified prediction |
/api/v2/intelligence/patterns |
GET | Session patterns |
/api/v2/intelligence/errors |
POST | Likely errors |
/api/v2/intelligence/feedback |
POST | Outcome feedback |
File Watcher
python3 scripts/session/watcher.py daemon # Start as background daemon
python3 scripts/session/watcher.py status # Check daemon status
python3 scripts/session/watcher.py stop # Stop daemon
Storage Modes
Priority: Qdrant → sqlite-vec → FTS fallback
- Qdrant: Full semantic search (requires server)
- sqlite-vec: Single-file vectors (offline capable)
- FTS: Full-text search fallback (always available)
Embedding Providers (SOTA 2026)
Priority: Cohere v4 → Cohere v3 → SBERT offline
Cohere embed-v4.0 (default):
- Multimodal (text + images)
- 128k context window
- Matryoshka dimensions: 256, 512, 1024, 1536
Dimension Options:
- 1536d: Maximum quality
- 1024d: Balanced (default)
- 512d: 50% storage savings
- 256d: 83% storage savings
Fallback Chain:
- Cohere v4 → Cohere v3 → SBERT (all-MiniLM-L6-v2)
Auto-switches on API failure. No manual configuration needed.
What's New in v5.0 — Chief of Staff (January 2026)
The AI Second Brain is now complete. Full infrastructure for sovereign knowledge management.
| Feature | Description |
|---|---|
| 🔮 Meta-Learning Engine | Predictive session intelligence from 666+ outcomes, 1,014 cognitive states |
| 🏛️ Storage Triad | SQLite (WAL mode, FTS5) + Qdrant (semantic search) |
| ⚖️ Writer-Critic System | 3 critics validate archives, evidence, and context packs |
| 🕸️ Graph Intelligence | 11,579 nodes, 13,744 edges — concept relationships & lineage |
| 🔌 REST API | 22 endpoints on port 3847 for cross-app integration |
| 📊 Oracle Consensus | Multi-stream validation for high-stakes outputs |
| 🎯 Evidence Layer | Citations, confidence scoring, source validation |
Chief of Staff Architecture
┌──────────────────────────────────────────────────────────────────────────────┐
│ CHIEF OF STAFF INFRASTRUCTURE │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ CAPTURE │───▶│ STORAGE │───▶│ INTELLIGENCE│───▶│ RETRIEVAL │ │
│ │ │ │ TRIAD │ │ │ │ API │ │
│ │ Sessions │ │ │ │ Writer │ │ │ │
│ │ URLs │ │ SQLite │ │ Critic │ │ REST /api/* │ │
│ │ Findings │ │ Qdrant │ │ Oracle │ │ Graph /v2 │ │
│ │ Transcripts │ │ Graph │ │ Evidence │ │ SDK │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────────────────────┐ │
│ │ GRAPH INTELLIGENCE │ │
│ │ │ │
│ │ Sessions ──contains──▶ Findings ──cites──▶ Papers │ │
│ │ │ │ │ │ │
│ │ └──────enables─────────┴────derives_from───┘ │ │
│ │ │ │
│ │ 11,579 Nodes • 13,744 Edges • Concept Clusters • Lineage │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
v4.0 Features (Still Available)
| Feature | Description |
|---|---|
| 🧠 CPB Module | Cognitive Precision Bridge — 5-path AI orchestration |
| 🎯 ELITE TIER | 5-agent ACE consensus, Opus-first routing, 0.75 DQ bar |
| 📊 DQ Scoring | Validity (40%) + Specificity (30%) + Correctness (30%) |
| 🔀 Smart Routing | Auto-select path based on query complexity |
CPB Execution Paths
┌─────────────────────────────────────────────────────────────────────────┐
│ COGNITIVE PRECISION BRIDGE (CPB) │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Query → [Complexity Analysis] → Path Selection → Execution → DQ Score │
│ │
│ ┌──────────┬──────────┬──────────┬──────────┬──────────┐ │
│ │ DIRECT │ RLM │ ACE │ HYBRID │ CASCADE │ │
│ │ <0.2 │ 0.2-0.5 │ 0.5-0.7 │ >0.7+ │ >0.7 │ │
│ │ Simple │ Context │ Consensus│ Combined │ Full │ │
│ │ ~1s │ ~5s │ ~5s │ ~10s │ ~15s │ │
│ └──────────┴──────────┴──────────┴──────────┴──────────┘ │
│ │
│ 5-Agent ACE Ensemble: │
│ 🔬 Analyst | 🤔 Skeptic | 🔄 Synthesizer | 🛠️ Pragmatist | 🔭 Visionary │
│ │
└─────────────────────────────────────────────────────────────────────────┘
🆕 CPB Precision Mode v2.0
Research-grounded answers with 95%+ quality target. Combines tiered search, grounded generation, and cutting-edge convergence research.
┌─────────────────────────────────────────────────────────────────────────┐
│ PRECISION MODE v2 PIPELINE │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Query │
│ │ │
│ ▼ PHASE 1: TIERED SEARCH (ResearchGravity methodology) │
│ │ ├── Tier 1: arXiv, Labs, Industry News │
│ │ ├── Tier 2: GitHub, Benchmarks, Social │
│ │ └── Tier 3: Internal learnings (Qdrant) │
│ │ │
│ ▼ PHASE 2: CONTEXT GROUNDING │
│ │ └── Build citation-ready context (agents cite ONLY these) │
│ │ │
│ ▼ PHASE 3: GROUNDED CASCADE (7 agents) │
│ │ └── 🔬🤔🔄🛠️🔭📚💡 with citation enforcement │
│ │ │
│ ▼ PHASE 4: MAR CONSENSUS (Multi-Agent Reflexion) │
│ │ └── ValidityCritic + EvidenceCritic + ActionabilityCritic │
│ │ │
│ ▼ PHASE 5: TARGETED REFINEMENT (IMPROVE pattern) │
│ │ └── Fix weakest DQ dimension per retry │
│ │ │
│ ▼ PHASE 6: EDITORIAL FRAME │
│ │ └── Extract thesis / gap / innovation direction │
│ │ │
│ ▼ Result (DQ score + verifiable citations) │
│ │
└─────────────────────────────────────────────────────────────────────────┘
| Feature | Description |
|---|---|
| Tiered Search | arXiv API + GitHub API + Internal Qdrant |
| Time-Decay Scoring | Research: 23-day half-life, News: 2-day |
| Signal Quantification | Stars, citations, dates extracted |
| Grounded Generation | Agents can ONLY cite retrieved sources |
| MAR Consensus | 3 persona critics → synthesis (arXiv:2512.20845) |
| Targeted Refinement | IMPROVE pattern (arXiv:2502.18530) |
Usage:
python3 -m cpb precision "your research question" --verbose
v3.5 Changelog
| Feature | Description |
|---|---|
| Precision Bridge Research | Tesla US20260017019A1 → RLM synthesis methodology |
| Cognitive Wallet Tracking | 114 sessions, 2,530 findings, 8,935 URLs, 27M tokens |
| Deep Dive Workflow | Multi-paper synthesis with implementation output |
| Framework Extraction | COMPRESS → EXPLORE → RECONSTRUCT pattern identified |
Notable Research Sessions
| Session | Papers | Output |
|---|---|---|
| Chief of Staff Architecture | 374 | Storage Triad, Graph Intelligence, Writer-Critic |
| Tesla Mixed-Precision RoPE | 15 arXiv | recursiveLanguageModel.ts implementation |
| Multi-Agent Orchestration | 12 arXiv | ACE/DQ Scoring in OS-App |
| CPB Integration | 8 arXiv | cpb/ Python module |
| 160+ Papers Meta-Synthesis | 160+ | Unified research index |
What's New in v3.4
| Feature | Description |
|---|---|
| Context Prefetcher | scripts/session/prefetch.py — Inject relevant learnings into Claude sessions |
| Learnings Backfill | scripts/backfill/backfill_learnings.py — Extract learnings from all archived sessions |
| Memory Injection | Auto-load project context, papers, and lineage at session start |
| Shell Integration | prefetch, prefetch-clip, prefetch-inject shell commands |
v3.3 Changelog
| Feature | Description |
|---|---|
| YouTube Research | scripts/importers/youtube_channel.py — Channel analysis and transcript extraction |
| Enhanced Backfill | Improved session recovery with better transcript parsing |
| Ecosystem Sync | Deeper integration with Agent Core orchestration |
v3.2 Changelog
| Feature | Description |
|---|---|
| Auto-Capture | Sessions automatically tracked — URLs, findings, full transcripts extracted |
| Lineage Tracking | Link research sessions to implementation projects |
| Project Registry | 4 registered projects with cross-referenced research |
| Context Loader | Auto-load project context from any directory |
| Unified Index | Cross-reference by paper, topic, or session |
| Backfill | Recover research from historical Claude sessions |
Why ResearchGravity?
Traditional research workflows fail at the frontier:
| Problem | Impact |
|---|---|
| Single-source blindspots | Missing critical signals |
| No synthesis | Raw links ≠ research |
| No session continuity | Context lost between sessions |
| No quality standard | Inconsistent output |
ResearchGravity solves this with:
- Multi-tier source hierarchy — Tier 1 (primary), Tier 2 (amplifiers), Tier 3 (context)
- Cold Start Protocol — Never lose session context
- Synthesis workflow — Thesis → Gap → Innovation Direction
- Quality checklist — Consistent Metaventions-grade output
Architecture
Directory Structure
ResearchGravity/
│
├── api/ # REST API Server (v5.0+)
│ ├── server.py # FastAPI on port 3847 — 25 endpoints
│ └── routes/ # API route modules
│
├── capture/ # Event capture & normalization
├── chrome-extension/ # Browser extension for URL capture
├── cli/ # CLI Package (v6.0) — REPL commands & UI
│
├── coherence_engine/ # Cross-platform coherence detection
├── cpb/ # Cognitive Precision Bridge (v4.0)
├── critic/ # Writer-Critic validation system (v5.0)
├── dashboard/ # Web dashboard UI
├── delegation/ # Intelligent delegation (arXiv:2602.11865)
│
├── docs/ # All documentation
│ ├── context-packs/ # Context pack design & implementation docs
│ ├── meta-learning/ # Meta-learning architecture docs
│ ├── phases/ # Phase completion records
│ ├── prds/ # Product requirement documents
│ ├── routing/ # Routing workflow docs
│ └── ucw/ # UCW whitepaper & cognitive profile
│
├── graph/ # Graph Intelligence (v5.0) — 11K nodes
├── mcp_raw/ # MCP protocol & embeddings layer
├── methods/ # Research methodology definitions
├── notebooklm_mcp/ # NotebookLM MCP server (37 tools)
│
├── scripts/ # All utility scripts
│ ├── backfill/ # Backfill & migration (9 scripts)
│ ├── coherence/ # Coherence analysis pipeline
│ ├── context-packs/ # Context pack build/select/metrics
│ ├── evidence/ # Evidence extraction & validation
│ ├── importers/ # Platform importers (ChatGPT, Grok, CLI)
│ ├── prediction/ # Intelligence & prediction engine
│ ├── proof/ # Demo proof & interactive deck
│ ├── routing/ # Routing metrics & research sync
│ ├── session/ # Session management (status, init, REPL)
│ └── visual/ # Visual generation scripts
│
├── storage/ # Storage Engine — SQLite + Qdrant + sqlite-vec
├── tests/ # All test files
├── ucw/ # Universal Cognitive Wallet
├── webhook/ # Webhook event receiver
│
├── mcp_server.py # MCP server entry point
├── setup.sh # Bootstrap script
├── requirements.txt # Python dependencies
└── ruff.toml # Linter config
CPB Module (v4.0)
The Cognitive Precision Bridge provides precision-aware AI orchestration.
Quick Start
from cpb import cpb, analyze, score_response
# Analyze query complexity
result = analyze("Design a distributed cache system")
print(f"Complexity: {result['complexity_score']:.2f}")
print(f"Path: {result['selected_path']}")
# Build ACE consensus prompts (5 agents)
prompts = cpb.build_ace_prompts("What's the best auth strategy?")
for p in prompts:
print(f"[{p['agent']}] {p['system_prompt'][:50]}...")
# Score response quality
dq = score_response(query, response)
print(f"DQ: {dq.overall:.2f} (V:{dq.validity:.2f} S:{dq.specificity:.2f} C:{dq.correctness:.2f})")
CLI Commands
# Analyze query complexity
python3 -m cpb.cli analyze "Your query here"
# Score a response
python3 -m cpb.cli score --query "Q" --response "R"
# View DQ statistics
python3 -m cpb.cli stats --days 30
# Check CPB status
python3 -m cpb.cli status
# Via routing-metrics
python3 scripts/routing/routing-metrics.py cpb analyze "Your query"
python3 scripts/routing/routing-metrics.py cpb status
ELITE TIER Configuration
| Setting | Value | Description |
|---|---|---|
| Complexity Thresholds | 0.2 / 0.5 | Lower = more orchestration |
| ACE Agent Count | 5 | Full ensemble |
| DQ Quality Bar | 0.75 | Higher standard |
| Default Path | cascade | Full pipeline |
| RLM Iterations | 25 | Deeper decomposition |
| Model Routing | Opus-first | Maximum quality |
5-Agent ACE Ensemble
| Agent | Role | Focus |
|---|---|---|
| 🔬 Analyst | Evidence evaluator | Data, logic, consistency |
| 🤔 Skeptic | Challenge assumptions | Failure modes, risks |
| 🔄 Synthesizer | Pattern finder | Connections, frameworks |
| 🛠️ Pragmatist | Feasibility checker | Implementation, constraints |
| 🔭 Visionary | Strategic thinker | Long-term, second-order effects |
Research Foundation
- arXiv:2512.24601 (RLM) - Recursive context externalization
- arXiv:2511.15755 (DQ) - Decisional quality measurement (since withdrawn by its author; V+S+C formula adapted)
- arXiv:2508.17536 - Voting vs Debate consensus strategies
Installation
Prerequisites
- Python 3.12 (what CI builds and tests against)
- pip or pipenv
Setup
# Clone the repository
git clone https://github.com/Dicoangelo/ResearchGravity.git
cd ResearchGravity
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install dependencies
pip install -r requirements.txt
Configuration
Create ~/.agent-core/config.json for API keys:
{
"cohere": {
"api_key": "your-cohere-api-key"
}
}
Or use environment variables:
export COHERE_API_KEY="your-cohere-api-key"
Optional (for API server):
export RG_SECRET_KEY=$(python -c "import secrets; print(secrets.token_hex(32))")
export RG_API_KEY="your-service-api-key"
Verify Installation
python3 scripts/session/status.py
ResearchGravity MCP questions
Can I use it offline?
Yes, the system provides offline capabilities through sqlite-vec for single-file vectors and FTS as a fallback.
What embedding providers are available?
It uses a fallback chain starting with Cohere v4, then Cohere v3, and finally SBERT (all-MiniLM-L6-v2) for offline use.