Reasoning Engine

An MCP server that brings difficulty-adaptive, multi-path reasoning to Claude Code. It implements the Actor-Critic-Planner-Reflexion (ACPR) pipeline for deep research synthesis.

What It Does

You give it a research question. It decides how hard the question is, allocates compute accordingly, explores multiple reasoning paths in parallel, scores each path, self-corrects weak paths, and synthesizes the best results into a coherent report.

"What is a Process Reward Model?"
  -> difficulty 0.21 -> single pass -> done in seconds

"How do PRMs interact with MCTS for test-time compute scaling?"
  -> difficulty 0.71 -> forest strategy -> 8 branches, 3 reflexion rounds

Architecture

Two components work together:

Claude Code (LLM-powered orchestrator)
  |  spawns parallel agents for generation, critique, reflexion
  |  calls MCP tools for algorithmic decisions
  v
Reasoning Engine MCP Server (deterministic Python backend)
  - Difficulty estimation
  - DORA budget allocation (explore vs exploit)
  - UCB branch selection
  - Dual-signal PRM scoring (Promise + Progress)
  - Research angle planning and evidence-gap checks
  - Tree state management (SQLite)
  - Episodic memory for cross-session learning
  - Content sanitization (prompt injection protection)

No API key required. Runs on your Claude Code Max subscription.

How It Works

The ACPR Pipeline

| Phase | What Happens | |-------|-------------| | Initialize | Estimate difficulty, allocate budget, recall past learnings | | Generate | Spawn parallel Actor agents, each exploring a different research angle | | Evaluate | Critic agents score each path on Promise (will it succeed?) and Progress (is it advancing?) | | Plan | DORA computes score variance (kappa) and decides: explore broadly or exploit the best path | | Reflect | Low-scoring paths get textual critique injected back for self-correction | | Loop | Repeat until budget exhausted or high-confidence result found | | Synthesize | Top paths merged into a coherent research report |

Difficulty-Adaptive Scaling

| Difficulty | Strategy | Branches | Reflexion | |-----------|----------|----------|-----------| | 0.0 - 0.3 | Single pass | 1 | None | | 0.3 - 0.5 | Best-of-N | 3 | 1 round | | 0.5 - 0.7 | Beam search | 5 | 2 rounds | | 0.7 - 1.0 | Forest | 8 | 3 rounds |

Installation

1. Clone and install

git clone https://github.com/Raoof128/reasoning-engine.git
cd reasoning-engine
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

2. Run tests

pytest -v

3. Configure Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "reasoning-engine": {
      "command": "/path/to/reasoning-engine/.venv/bin/mcp",
      "args": ["run", "/path/to/reasoning-engine/src/reasoning_engine/server.py"],
      "env": {
        "REASONING_ENGINE_DB": "/path/to/reasoning-engine/reasoning.db"
      }
    }
  }
}

4. Install the skill (optional)

Copy skill/deep-research.md to ~/.claude/skills/deep-research.md for the /deep-research slash command.

Required Skills and MCP Servers

This agent works with the following Claude Code components:

Required MCP Servers

| MCP Server | Purpose | How to Get | |-----------|---------|-----------| | reasoning-engine | Core reasoning backend (this repo) | Install from this repo | | crawl4ai | Web crawling for live research | Built-in Claude Code MCP |

Required Skills (for full pipeline)

| Skill | Purpose | Pipeline Phase | Source | |-------|---------|---------------|--------| | deep-research | Orchestrates the ACPR reasoning loop | Phases 1-7 | Included in this repo | | stop-slop | Removes AI writing patterns from synthesis | Phase 8 | by Hardik Pandya | | docx | Generates publication-quality Word documents | Phase 9 | by Anthropic |

Optional Skills

| Skill | Purpose | Source | |-------|---------|--------| | theme-factory | Apply visual themes to the output document | by Anthropic |

Install the deep-research skill:

cp skill/deep-research.md ~/.claude/skills/

The stop-slop and docx skills are third-party — see their repos for installation.

MCP Tools

| Tool | Purpose | |------|---------| | init_research_session | Create session, estimate difficulty, allocate budget | | register_branch | Register a reasoning branch with trace and sources | | score_branch | Record dual-signal score (Promise + Progress + critique) | | select_next_branches | DORA allocation: explore vs exploit based on kappa | | check_termination | Should we stop? (budget, confidence, convergence) | | consensus_candidates | Top-K branches for final synthesis | | record_reflection_tool | Store a Reflexion cycle's critique and revision | | recall_memory_tool | Retrieve relevant learnings from past sessions | | save_to_memory | Persist episodic memory for future recall | | sanitize_content | Strip HTML, scripts, and prompt injection patterns | | get_session_state | Full session state for debugging | | plan_research_angles_tool | Create prioritized research angles and starter questions | | evidence_gap_questions_tool | Generate verification questions for claims before synthesis |

Project Structure

reasoning-engine/
  src/reasoning_engine/
    server.py       # FastMCP server wiring all tools
    db.py           # SQLite schema and connections
    difficulty.py   # Heuristic difficulty estimator
    dora.py         # DORA budget allocation + branch selection
    ucb.py          # UCB1 explore/exploit selection
    sessions.py     # Session and branch lifecycle management
    memory.py       # Episodic memory for Reflexion learnings
    research.py     # Research angle and evidence-gap planning
    sanitizer.py    # Content sanitization for web data
  tests/            # 38 tests, all passing
  skill/            # Claude Code skill file

Background

This project implements ideas from three research documents on AI reasoning architectures:

• Process Reward Models score individual reasoning steps (not just final answers), enabling dense feedback for tree search.
• DORA (Direction-Oriented Resource Allocation) uses score variance to dynamically switch between exploring many paths and exploiting the best one.
• Reflexion injects textual critiques back into the prompt, enabling self-correction without weight updates.
• UCB1 selection balances trying promising branches against exploring undervisited ones.
• ReAct / Self-RAG style evidence checks keep retrieval and verification explicit before synthesis.

The key insight: a Claude Code skill can orchestrate this entire pipeline using parallel agent spawning on a Max subscription, with a lightweight Python MCP server handling the deterministic math. No separate API key needed.

Documentation

• Architecture Overview
• API Reference
• Usage Examples
• Contributing
• Security Policy
• Code of Conduct

Verifiable Research Engine MVP

Run a local verifiable research pipeline:

reasoning-engine research "Scholar Gateway exposes semantic search" \
  --draft "Scholar Gateway exposes semantic search."

Run a Scholar Gateway search with mocked default retrieval:

reasoning-engine scholar search "MCP prompt injection" --limit 3

Live Scholar Gateway calls are opt-in:

export SCHOLAR_GATEWAY_LIVE=1
export SCHOLAR_GATEWAY_ACCESS_TOKEN="<token>"
reasoning-engine scholar search "literature synthesis evaluation" --limit 5

Tokens are read from environment or local credential mechanisms. Tokens are not stored in SQLite or run packs. MVP verification uses deterministic lexical overlap as a placeholder verifier, so it is suitable for pipeline testing and audit workflow validation rather than final semantic claim verification.

Local HTTP MCP

STDIO remains the default MCP workflow. To start a local Streamable HTTP MCP server:

reasoning-engine serve --transport http --host 127.0.0.1 --port 8765

The MCP endpoint is available at:

http://127.0.0.1:8765/mcp

Public binding is blocked unless explicitly acknowledged:

reasoning-engine serve --transport http --host 0.0.0.0 --unsafe-bind-public

For Notion AI Custom MCP testing through a Cloudflare HTTPS tunnel, use the laptop launcher:

chmod +x ./run-notion-mcp-laptop.sh
./run-notion-mcp-laptop.sh

On macOS, you can also double-click run-notion-mcp-laptop.command from Finder to start the same launcher in Terminal.

The launcher keeps the MCP server bound to 127.0.0.1, creates a local bearer token file at ~/.reasoning-engine/notion-http.env, starts a temporary Cloudflare Tunnel, and prints the Notion MCP URL. See Notion Laptop MCP Tunnel.

The project requires mcp>=1.24.0,<2, which is above the 1.23.0 safety floor for default FastMCP DNS rebinding protection.

License

MIT