Metadata-Version: 2.5
Name: elite-reasoning-mcp
Version: 2.5.0
Summary: The Unified Cognitive Operating System for AI Coding Agents: 9-Stage Cognitive Loop, Process Reward Model (PRM), Deterministic AST Invariant Gates, Stanford STORM Deep Research, and Trusted Memory.
Project-URL: Homepage, https://github.com/Snehgabani/elite-reasoning-mcp
Project-URL: Repository, https://github.com/Snehgabani/elite-reasoning-mcp
Project-URL: Documentation, https://github.com/Snehgabani/elite-reasoning-mcp#readme
Project-URL: Bug Tracker, https://github.com/Snehgabani/elite-reasoning-mcp/issues
Project-URL: Changelog, https://github.com/Snehgabani/elite-reasoning-mcp/blob/main/CHANGELOG.md
Author-email: Sneh Gabani <snehgabani@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agent-memory,ai-agent,ai-coding,ai-ide,ai-tools,anti-pattern,ast-gating,claude,coding-agent,confidence-calibration,cursor,decision-making,deepeval,evals,gemini,inspect-ai,knowledge-graph,llm,mcp,mcp-server,memory,model-context-protocol,process-reward-model,promptfoo,reasoning,reasoning-safety,release-automation,self-discover,storm-research,vscode,windsurf,workflow-automation,workflow-recorder
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.15.0
Requires-Dist: fastapi<1,>=0.141.1
Requires-Dist: fastmcp>=2.14.0
Requires-Dist: httpx<1,>=0.28.1
Requires-Dist: langchain-core>=1.5.6
Requires-Dist: langchain-openai>=1.5.1
Requires-Dist: langchain>=1.3.15
Requires-Dist: langgraph>=1.2.11
Requires-Dist: mcp>=1.3.0
Requires-Dist: networkx>=3.6.1
Requires-Dist: pydantic<3,>=2.13.4
Requires-Dist: python-dotenv<2,>=1.2.3
Requires-Dist: rich<16,>=15.0.0
Requires-Dist: scipy>=1.17.1
Requires-Dist: uvicorn<1,>=0.52.3
Provides-Extra: all
Requires-Dist: bandit<2,>=1.9.4; extra == 'all'
Requires-Dist: langchain-core>=1.5.6; extra == 'all'
Requires-Dist: langgraph>=1.2.11; extra == 'all'
Requires-Dist: networkx>=3.6.1; extra == 'all'
Requires-Dist: pyright; extra == 'all'
Requires-Dist: pytest; extra == 'all'
Requires-Dist: pytest-asyncio; extra == 'all'
Requires-Dist: ruff; extra == 'all'
Requires-Dist: sentence-transformers>=6.0.0; extra == 'all'
Requires-Dist: sqlite-vec>=0.1.9; extra == 'all'
Provides-Extra: dev
Requires-Dist: bandit<2,>=1.9.4; extra == 'dev'
Requires-Dist: pyright; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: graph
Requires-Dist: langchain-core>=1.5.6; extra == 'graph'
Requires-Dist: langgraph>=1.2.11; extra == 'graph'
Requires-Dist: networkx>=3.6.1; extra == 'graph'
Provides-Extra: vectors
Requires-Dist: sentence-transformers>=6.0.0; extra == 'vectors'
Requires-Dist: sqlite-vec>=0.1.9; extra == 'vectors'
Description-Content-Type: text/markdown

# Elite Reasoning MCP

**Model Context Protocol workflow memory, evaluation, and reasoning-safety layer for AI coding agents.**

<p align="center">
  <img src="assets/hero-banner.png" alt="Elite Reasoning MCP" width="100%">
</p>

<p align="center">
  <strong>Give coding agents a compact, evidence-gated workflow layer with trusted memory and local release verification.</strong>
</p>

<p align="center">
  <a href="https://github.com/Snehgabani/elite-reasoning-mcp/actions/workflows/ci.yml"><img src="https://github.com/Snehgabani/elite-reasoning-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/Snehgabani/elite-reasoning-mcp/actions/workflows/codeql.yml"><img src="https://github.com/Snehgabani/elite-reasoning-mcp/actions/workflows/codeql.yml/badge.svg" alt="CodeQL"></a>
  <a href="https://github.com/Snehgabani/elite-reasoning-mcp/actions/workflows/secret-scan.yml"><img src="https://github.com/Snehgabani/elite-reasoning-mcp/actions/workflows/secret-scan.yml/badge.svg" alt="Secret Scan"></a>
  <a href="https://github.com/Snehgabani/elite-reasoning-mcp/actions/workflows/scorecard.yml"><img src="https://github.com/Snehgabani/elite-reasoning-mcp/actions/workflows/scorecard.yml/badge.svg" alt="OpenSSF Scorecard"></a>
  <a href="https://pypi.org/project/elite-reasoning-mcp/"><img src="https://img.shields.io/pypi/v/elite-reasoning-mcp?style=flat-square&color=blue" alt="PyPI"></a>
  <a href="https://pypi.org/project/elite-reasoning-mcp/"><img src="https://img.shields.io/pypi/dm/elite-reasoning-mcp?style=flat-square&color=green" alt="Downloads"></a>
  <a href="https://pypi.org/project/elite-reasoning-mcp/"><img src="https://img.shields.io/pypi/pyversions/elite-reasoning-mcp?style=flat-square" alt="Python"></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/Snehgabani/elite-reasoning-mcp?style=flat-square" alt="License"></a>
  <a href="SECURITY.md"><img src="https://img.shields.io/badge/security-policy-brightgreen?style=flat-square" alt="Security Policy"></a>
  <a href="https://github.com/Snehgabani/elite-reasoning-mcp/stargazers"><img src="https://img.shields.io/github/stars/Snehgabani/elite-reasoning-mcp?style=flat-square" alt="Stars"></a>
</p>

<p align="center">
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-features">Features</a> •
  <a href="#who-this-is-for">Use Cases</a> •
  <a href="#%EF%B8%8F-architecture">Architecture</a> •
  <a href="#-core-tools-default">Core Tools</a> •
  <a href="#-configuration">Config</a> •
  <a href="#-security--trust">Security</a> •
  <a href="#-contributing">Contributing</a>
</p>

---

## Why Elite Reasoning?

Every AI coding assistant makes the **same mistakes twice**. Elite Reasoning fixes that.

It's a [Model Context Protocol](https://modelcontextprotocol.io/) server for AI IDEs and coding agents. It adds a **persistent workflow layer** with evidence-gated execution, quality-gated memory, release verification, local monitoring, and prevention guidance.

Elite Reasoning does not claim to make a smaller model frontier-capable. It makes bounded coding workflows more reliable by reducing tool-selection noise, preserving trusted context, requiring evidence before completion, and returning typed MCP contracts.

> **One install. Zero config. Works with Cursor, Antigravity, VS Code + Continue, Windsurf, and any MCP-compatible IDE.**

### Who This Is For

- Developers who use Cursor, Claude Desktop, Gemini CLI, VS Code + Continue, Windsurf, or another MCP-compatible AI IDE.
- AI coding-agent users who want persistent memory without blindly injecting stale, low-trust, or sensitive context.
- Maintainers who need auditable multi-step execution, release gates, risk checks, and repeatable eval scaffolds.
- Teams building agentic development workflows that need reasoning safety, confidence calibration, and workflow evidence.

### The Problem

| Without Elite Reasoning | With Elite Reasoning |
|:---|:---|
| LLM forgets past mistakes | ✅ Anti-pattern memory prevents repeats |
| No confidence tracking | ✅ Brier-scored calibration per prediction |
| Generic responses | ✅ Intent-classified, complexity-scored routing |
| No decision audit trail | ✅ Every architectural decision logged + searchable |
| Manual quality checks | ✅ Automated pre-commit audits + FMEA risk gates |
| Multi-step work gets lost | ✅ `elite_prepare` creates durable evidence + validation gates |
| Memory can poison context | ✅ Trust/confidence/privacy gates quarantine risky memories |

---

## ⚡ Quick Start

### One-Line Install

```bash
pip install elite-reasoning-mcp
```

For an isolated CLI installation:

```bash
uv tool install elite-reasoning-mcp

# Verify the actual binary your IDE will run
elite-reasoning-mcp --version
elite-reasoning-mcp doctor --json

# Preview a safe standalone upgrade command
elite-reasoning-mcp upgrade --dry-run
```

### Add to your IDE

**Antigravity / Gemini CLI** (`~/.gemini/config/mcp_config.json`):
```json
{
  "mcpServers": {
    "elite-reasoning": {
      "command": "elite-reasoning-mcp",
      "args": [],
      "env": {
        "ELITE_BRAIN_DIR": "~/.elite-reasoning/brain",
        "ELITE_TOOL_PROFILE": "core"
      }
    }
  }
}
```

**Cursor** (`.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "elite-reasoning": {
      "command": "elite-reasoning-mcp",
      "env": {
        "ELITE_BRAIN_DIR": "~/.elite-reasoning/brain",
        "ELITE_TOOL_PROFILE": "core"
      }
    }
  }
}
```

**VS Code + Continue** (`~/.continue/config.yaml`):
```yaml
mcpServers:
  - name: elite-reasoning
    command: elite-reasoning-mcp
    env:
      ELITE_BRAIN_DIR: ~/.elite-reasoning/brain
      ELITE_TOOL_PROFILE: core
```

### Activate the Pipeline

Add this to your IDE's system prompt (e.g., `~/.gemini/GEMINI.md` or Cursor Rules):

```markdown
## ⚡ RULE #0 — ELITE MCP PIPELINE

For non-trivial build, debug, research, audit, or release tasks, start with:

elite_prepare(user_prompt="<the user's exact message>")

Update each step with evidence before claiming completion:

elite_progress(run_id="<run id>", action="update", step_index=1, step_status="passed", evidence="<proof>")

Before shipping, call:

elite_verify(check="doctor")

Skip tool calls for trivial acknowledgements like "ok", "thanks", "yes", "no".
```

**That's it.** Restart your IDE and every conversation automatically benefits from the reasoning pipeline.

---

## 🚀 Features

### 🧠 Evidence-Gated Workflow
When the IDE calls `elite_prepare`, the server creates a durable plan with risk-aware validation gates, trusted memory context, and a compact typed response. `elite_progress` rejects out-of-order completion and terminal claims without evidence.

### 🛡️ Anti-Pattern Memory
Past mistakes are recorded with root-cause analysis and automatically surfaced when similar patterns appear. Your AI literally learns from its errors.

### 📊 Confidence Calibration
Track prediction accuracy with proper Brier scores. Know when your AI is overconfident vs. well-calibrated. Every prediction gets a confidence score and outcome tracking.

### ⚖️ Decision Council
Critical decisions get a 5-perspective adversarial review — optimist, pessimist, pragmatist, innovator, and devil's advocate — before committing.

### 🔒 Prevention Rules
Custom auto-triggered rules for your workflow. Define patterns that should trigger warnings, blocks, or automatic corrections. Rules self-improve through a learning pipeline.

### 📈 8-Layer Middleware Chain
Every tool call passes through usage logging, latency measurement, prevention rules, anti-pattern injection, periodic scanning, cost tracking, fallback guidance, and real transient retries. Structured gateway responses retain a stable `warnings` field rather than receiving ad-hoc text wrappers.

### 🧪 Risk Analysis
FMEA (Failure Mode & Effects Analysis), Swiss Cheese audits, smoke test gates, and pre-mortem simulations — all built-in, all callable as MCP tools.

### 💾 Persistent Memory
Cross-session knowledge stays scoped, trust-weighted, and privacy-gated. Secret-like content is redacted before storage; low-trust, sensitive, expired, and remotely imported items remain quarantined until an explicit approval action promotes them. Sensitive records cannot be promoted, and `elite_memory(action="forget")` permanently removes a selected local item.

### 🧭 Workflow Flight Recorder
`elite_prepare` records a durable execution contract, while `elite_progress` requires ordered evidence before completion. This gives agent work a recoverable audit trail without pretending the server executed the task itself.

### 🏥 Release Doctor And Local Monitoring
`elite_verify(check="doctor")` checks runtime identity, protocol version, dependencies, DB schema, capability routing, exposed tool count, active IDE mismatch, and release blockers before shipping. `elite_admin(action="monitoring")` returns local aggregate latency, workflow, and memory health without exporting prompt content.

### 🧪 Eval Harness Exports
The explicit `legacy` profile retains `export_eval_harness` for optional Promptfoo, DeepEval, and Inspect AI scaffolds. The default profile stays compact so agents can select the correct workflow actions reliably.

---

## 🏗️ Architecture

```
Your Task
    ↓
elite_prepare (typed workflow contract)
    ↓
┌──────────────────────────────────────────────┐
│  Intent and risk      → bounded workflow     │
│  Trusted memory       → scoped context       │
│  Prevention engine    → phase guidance       │
│  Validation gates     → evidence requirements │
│  Typed output         → stable MCP contract  │
└──────────────────────────────────────────────┘
    ↓
elite_progress (ordered evidence updates)
    ↓
elite_verify / elite_admin (release + monitoring)
    ↓
┌──────────────────────────────────────────────┐
│ Local-first telemetry and memory boundaries    │
│ Metadata by default; raw retention opt-in      │
│ Remote memory remains quarantined until review │
└──────────────────────────────────────────────┘
```

---

## 🔧 Core Tools (default)

The default v2 profile intentionally exposes five task-oriented tools. This improves tool selection, output-contract reliability, and safety for every MCP client.

| Tool | Description |
|:-----|:------------|
| `elite_prepare` | Create a durable, evidence-gated workflow contract for a task. |
| `elite_progress` | Read or update ordered workflow steps with evidence requirements. |
| `elite_verify` | Run release doctor or IDE capability verification. |
| `elite_memory` | Search, write, approve low-trust memory, or permanently forget a local memory item. |
| `elite_admin` | Inspect runtime identity, privacy policy, and local aggregate monitoring. |

### Legacy Catalog (explicit opt-in)

Existing installations can retain the full legacy tool catalog by setting `ELITE_TOOL_PROFILE=legacy`. It is not the default because a broad discovery surface makes selection less reliable for agents. The legacy profile includes the following 90+ tools and resources:

<details>
<summary><strong>Core Pipeline (3)</strong></summary>

| Tool | Description |
|:-----|:------------|
| `orchestrate_request_tool` | Master routing — fires on every prompt, classifies intent, routes to tools |
| `reasoning_preflight` | Pre-flight checklist for complex tasks |
| `assess_confidence` | Score confidence before committing to a plan |

</details>

<details>
<summary><strong>Workflow, Release & Eval (8)</strong></summary>

| Tool | Description |
|:-----|:------------|
| `workflow_run` | Create a durable evidence-gated execution contract |
| `workflow_status` | Inspect persisted workflow run status |
| `workflow_update_step` | Attach validation evidence to workflow steps |
| `elite_doctor` | Human-readable release-readiness health check |
| `elite_doctor_json` | Structured release-readiness report |
| `export_eval_harness` | Generate Promptfoo, DeepEval, and Inspect AI eval scaffolds |
| `remember_context` | Store quality-gated scoped memory |
| `memory_context_pack` | Retrieve trusted memory context for a task |

</details>

<details>
<summary><strong>Quality & Anti-Patterns (6)</strong></summary>

| Tool | Description |
|:-----|:------------|
| `check_anti_patterns` | Semantic search over past mistakes |
| `record_mistake` | Log mistakes with root cause analysis |
| `record_quality_score` | Score output quality (1-10) |
| `get_quality_trend` | Track quality trends over time |
| `pre_commit_audit` | Audit code before delivering |
| `bias_scan` | Detect cognitive biases in reasoning |

</details>

<details>
<summary><strong>Decision Making (6)</strong></summary>

| Tool | Description |
|:-----|:------------|
| `record_decision` | Log architectural decisions with rationale |
| `search_decisions` | Query past decisions (FTS + semantic) |
| `decision_council_review` | 5-perspective adversarial review |
| `adopt_vs_build` | Build-or-adopt analysis framework |
| `socratic_challenge` | Challenge your own plan's assumptions |
| `after_action_review` | Post-mortem structured review |

</details>

<details>
<summary><strong>Risk Analysis (5)</strong></summary>

| Tool | Description |
|:-----|:------------|
| `fmea_analysis` | Failure Mode & Effects Analysis |
| `fmea_risk_gate` | Risk threshold gate (block if RPN too high) |
| `smoke_test_gate` | Pre-deploy smoke test |
| `swiss_cheese_audit` | Multi-layer safety audit (Reason model) |
| `simulate_future_regrets` | Pre-mortem / regret simulation |

</details>

<details>
<summary><strong>Confidence & Calibration (3)</strong></summary>

| Tool | Description |
|:-----|:------------|
| `calibration_predict` | Log predictions with confidence % |
| `calibration_resolve` | Record actual outcomes |
| `calibration_score` | Brier score accuracy report |

</details>

<details>
<summary><strong>Memory & Knowledge Graph (5)</strong></summary>

| Tool | Description |
|:-----|:------------|
| `ingest_context` | Store cross-session knowledge |
| `memory_search_context` | Semantic search over memory |
| `memory_sync_decisions` | Persist decisions to long-term memory |
| `memory_sync_mistakes` | Persist mistakes to memory |
| `query_temporal_graph` | Knowledge graph queries with time decay |

</details>

<details>
<summary><strong>Goals & Benchmarks (7)</strong></summary>

| Tool | Description |
|:-----|:------------|
| `set_goal` | Define goals with key results |
| `check_goals` | Review active goals |
| `update_goal` | Update goal progress |
| `archive_goal` / `delete_goal` | Lifecycle management |
| `benchmark_track` | Track performance benchmarks |
| `get_tool_usage_stats` | Tool usage analytics |

</details>

<details>
<summary><strong>Learning & Autonomy (12)</strong></summary>

| Tool | Description |
|:-----|:------------|
| `record_prompt_intent` | Track prompt patterns |
| `analyze_prompt_sequence` | Session analysis |
| `get_user_thinking_model` | Cognitive model of user patterns |
| `update_thinking_pattern` | Update learned patterns |
| `register_prevention_rule` | Create custom auto-rules |
| `list_prevention_rules` | View active rules |
| `predictive_prevention` | Predict failures before they happen |
| `autonomous_scan` | Self-improvement scan |
| `self_diagnose` | System health diagnostic |
| `get_autonomous_status` | Autonomy rate and gap report |
| `generate_autonomous_goals` | Auto-generate improvement goals |
| `record_missed_detection` | Log when the system should have caught something |

</details>

<details>
<summary><strong>Quantitative Reasoning (5)</strong></summary>

| Tool | Description |
|:-----|:------------|
| `bayesian_update` | Bayesian probability updates |
| `calculate_expected_value` | Expected value calculations |
| `compound_growth` | Compound growth modeling |
| `five_whys` | Root cause analysis (5 Whys) |
| `validate_predictions` | Validate prediction batches |

</details>

<details>
<summary><strong>Collaboration (5)</strong></summary>

| Tool | Description |
|:-----|:------------|
| `get_user_profile` | User preference profile |
| `update_user_config` | Update user settings |
| `list_team_users` | Team user management |
| `share_skill` | Share learned skills |
| `sync_team_memory` | Sync memory across team |

</details>

<details>
<summary><strong>Natural Language Verbs (6)</strong></summary>

| Tool | Description |
|:-----|:------------|
| `plan` | Create structured plans |
| `analyze` | Deep analysis mode |
| `audit` | Comprehensive audit |
| `predict` | Make tracked predictions |
| `learn` | Learn from outcomes |
| `introspect` | Self-reflection on reasoning |

</details>

<details>
<summary><strong>Hypothesis & Prospective (5)</strong></summary>

| Tool | Description |
|:-----|:------------|
| `record_hypothesis` | Log testable hypotheses |
| `resolve_hypothesis` | Record hypothesis outcomes |
| `record_prospective_failure` | Pre-register potential failures |
| `resolve_prospective_failure` | Record failure outcomes |
| `search_thinking_patterns` | Search learned patterns |

</details>

<details>
<summary><strong>Unified Cognitive Singularity & MIX MCP Pipeline (42)</strong></summary>

| Tool | Description |
|:-----|:------------|
| `execute_mix` | 9-Stage Supreme Cognitive Pipeline (Meta-Routing + Bias Scan + Dynamic Topology + PRM Invariant Gate + PoW) |
| `elite_reason` | High-deliberation reasoning execution pipeline |
| `execute_singularity` | Drop-in backward-compatible entry point for `execute_mix` |
| `prm_verify_step` | Process Reward Model step verification (Math invariants, AST syntax, quantifier biases) |
| `compose_reasoning_topology` | Dynamic reasoning DAG topology composition via Self-Discover framework |
| `think_on_graph_search` | Think-on-Graph (ToG) beam search over knowledge graphs |
| `verify_argument` | Syllogism and logical fallacy verification with deterministic fail-safes |
| `expert_panel` | Concurrent dialectical viewpoint evaluation across domain expert personas |
| `repo_search` | Codebase AST property graph search for symbol definitions and references |
| `repo_impact_map` | Blast radius, dependency tree, and impacted test analysis for code changes |
| `apply_reasoning_diff` | Physical disk write barrier gated by HMAC-SHA256 authorization and AST syntax pre-flight |
| `fuzz_symbol` | Property-based testing for code symbols discovering edge case failures |
| `god_tier_reasoning` | N-candidate parallel reasoning with Constitutional Rubric Rejection Sampling |
| `hard_reason` | Language Agent Tree Search (LATS) with executable verifiers |
| `dual_process_route` | System 1 (fast heuristic) vs System 2 (deep deliberate graph) dynamic router |
| `self_rag_evaluate` | Self-RAG reflection token evaluation (relevance, support, utility) |
| `skeleton_of_thought_generate` | Concurrent parallel expansion of structured skeleton points |
| `live_web_search` | Multi-engine live search with semantic re-ranking |
| `red_team_attack` | Adversarial counter-hypothesis and failure mode stress-testing |
| `epistemic_verify` | Atomic proposition deconstruction and authoritative verification |
| `triangulate_claim` | Multi-source cross-referencing and verification |
| `deep_read` | Full markdown extraction, chunking, and semantic filtering on URLs |
| `temporal_verify` | Historical and temporal validity verification against timestamped records |
| `devils_advocate` | Dialectical revision loop challenging assumptions |
| `epistemic_research` | Multi-phase deep epistemic research with provenance tracking |
| `verify_claims` | Automated claim extraction and verification pipeline |
| `deep_research_report` | Stanford STORM Deep Research Engine with Table of Contents and citations |
| `autonomous_research` | Iterative research loop decomposing complex questions |
| `candidate_search` | Multi-solution candidate generation and automated scoring |
| `verify_candidate` | Candidate solution verification via sandbox execution or rubric |
| `reflexion_fix` | Minimal repair plan generation with automated lesson extraction |
| `compile_skills` | Compiles successful traces into task-specific exemplar prompts |
| `get_workspace_file` | Reads workspace files directly into reasoning state |
| `get_live_watcher_status` | Real-time live telemetry, active cognitive graphs, and watchdog health status |

</details>

Plus **7 MCP Resources** (`elite://profile`, `elite://anti_patterns`, `elite://decisions`, `elite://quality`, `elite://health`, `elite://goals`, `elite://benchmarks`) for real-time dashboards.

---

## ⚙️ Configuration

### Environment Variables

| Variable | Default | Description |
|:---------|:--------|:------------|
| `ELITE_BRAIN_DIR` | `~/.elite-reasoning/brain` | Where to store persistent memory |
| `ELITE_TOOL_PROFILE` | `core` | `core` exposes five typed gateway tools; `legacy` enables the compatibility catalog. |
| `ELITE_TELEMETRY_MODE` | `metadata` | `off`, `metadata`, `summary`, or `raw`; raw requires a second opt-in. |
| `ELITE_ALLOW_RAW_TELEMETRY` | unset | Must be `1` before `ELITE_TELEMETRY_MODE=raw` is honored. |
| `ELITE_ALLOW_RAW_PROMPT_STORAGE` | unset | Must be `1` to retain redacted raw prompts; otherwise prompts are hashed and withheld. |
| `ELITE_SYNC_ALLOWED_HOSTS` | localhost only | Comma-separated approved sync hosts. |
| `ELITE_SYNC_ALLOW_NETWORK` | unset | Must be `1` for approved non-local sync hosts. |
| `ELITE_SYNC_ALLOW_OUTBOUND` | unset | Must be `1` before legacy sync can push local decisions or anti-patterns. |
| `ELITE_SYNC_BIND_ALL_INTERFACES` | unset | Required with a sync API key before the optional hub can bind beyond localhost. |
| `SYNC_USER_KEYS_JSON` | unset | Optional sync-hub JSON mapping of user IDs to distinct API keys for auditable multi-user attribution. |
| `SYNC_SINGLE_USER_ID` | `single-user` | Server-side actor label for a single-user hub using `SYNC_API_KEY`. |
| `ELITE_SYNC_ENABLE_LLM_JUDGE` | unset | Required with `GEMINI_API_KEY` before the hub sends submissions to an external LLM judge. |
| `ELITE_ENABLE_LEGACY_INTERCEPTOR` | `0` | Enable legacy monkey-patch interceptor |
| `ELITE_GEMINI_BASE_URL` | (built-in) | HTTPS Gemini endpoint; a non-Google host also requires `ELITE_ALLOW_CUSTOM_GEMINI_ENDPOINT=1`. |

The local profile is created with owner-only permissions at `~/.elite-reasoning/config.json`; it is not read from the repository checkout and must never be committed. Neutral configuration and team-memory shapes are available in [docs/examples/local-profile.example.json](docs/examples/local-profile.example.json) and [docs/examples/team-memory.example.json](docs/examples/team-memory.example.json). Keep credentials in process environment variables or an OS keychain, not in JSON.

### Development Setup

```bash
# Clone the repo
git clone https://github.com/Snehgabani/elite-reasoning-mcp.git
cd elite-reasoning-mcp

# Install with dev dependencies
uv sync --extra dev

# Run the release gate used by CI
uv run python scripts/release_check.py

# Build package
uv build
```

---

## 🧪 Testing

```bash
# Run all tests
ELITE_BRAIN_DIR=/tmp/elite-test uv run pytest tests/ -v --tb=short

# Run the full release gate: tests, lint, types, high-severity scan,
# package privacy/content inspection, wheel CLI, and MCP smoke
uv run python scripts/release_check.py

# Run with coverage
uv run pytest tests/ --cov=core --cov-report=html
```

The test suite covers:
- ✅ Persistent store (CRUD, FTS, graph, goals, benchmarks)
- ✅ Graph store (nodes, edges, temporal queries, hypotheses)
- ✅ Connection pooling and stale connection recovery
- ✅ FTS sanitization (injection prevention)
- ✅ Workflow flight recorder and MCP tool exposure
- ✅ stdio MCP protocol identity, structured output, and `isError=true` failures
- ✅ privacy-safe telemetry, secret migration, approved sync, and memory quarantine
- ✅ ordered workflow evidence, prevention events, retry, fallback, and local monitoring
- ✅ Quality-gated memory quarantine
- ✅ Release doctor and eval harness exporters

---

## 🔐 Security & Trust

Elite Reasoning MCP is local-first by default: memory is stored under `ELITE_BRAIN_DIR`, telemetry stores metadata rather than prompt content, and external API access is opt-in through environment configuration.

The default profile does not expose network sync tools. In the explicit legacy profile, every sync request requires `confirm=true`, an allowlisted endpoint, redirect blocking, and environment grants for external or outbound traffic. The optional sync hub binds to localhost by default; external binding needs configured credentials and `ELITE_SYNC_BIND_ALL_INTERFACES=1`. For multi-user deployments, configure distinct credentials with `SYNC_USER_KEYS_JSON`; the hub derives contributor attribution from the credential and never trusts a caller-supplied user ID. Imported remote records are stored as low-trust quarantined memory until an operator explicitly approves them. External LLM judging is disabled unless both `GEMINI_API_KEY` and `ELITE_SYNC_ENABLE_LLM_JUDGE=1` are set.

Public repository hardening includes:
- `SECURITY.md` with supported versions, private vulnerability reporting, and memory/privacy boundaries
- Dependabot for Python, GitHub Actions, and telemetry UI dependencies
- CodeQL scanning for Python security issues
- Dependency Review on pull requests
- OpenSSF Scorecard visibility for supply-chain posture
- Immutable GitHub Action and Docker image pins, with Dependabot update coverage
- GitHub build provenance and PyPI digital attestations for release distributions
- An allowlisted source distribution plus a release gate that rejects local profiles, generated UI output, databases, and credential-like files
- A checksum-verified, read-only Gitleaks workflow that scans full Git history and the checked-out files with redacted findings
- Release-gate evidence via `scripts/release_check.py`

Security reports should use [GitHub private vulnerability reporting](https://github.com/Snehgabani/elite-reasoning-mcp/security/advisories/new), not public issues.

For the next tracking and monitoring layer, see the [Elite Telemetry Roadmap](docs/elite_telemetry_roadmap.md).

---

## 🤝 Contributing

Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), [GOVERNANCE.md](GOVERNANCE.md), and the security boundaries in [SECURITY.md](SECURITY.md).

1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Run** the release gate (`uv run python scripts/release_check.py`)
4. **Document** MCP behavior, privacy impact, and validation evidence in your PR
5. **Commit** your changes (`git commit -m 'feat: add amazing feature'`)
6. **Push** to the branch (`git push origin feature/amazing-feature`)
7. **Open** a Pull Request

### Commit Convention

We use [Conventional Commits](https://www.conventionalcommits.org/):
- `feat:` — New features
- `fix:` — Bug fixes
- `chore:` — Maintenance
- `docs:` — Documentation

---

## 📄 License

MIT © [Sneh Gabani](https://github.com/Snehgabani)

---

<p align="center">
  <sub>Built for the AI-native developer workflow</sub>
</p>
<p align="center">
  <a href="https://github.com/Snehgabani/elite-reasoning-mcp/stargazers">Star us on GitHub</a> •
  <a href="https://pypi.org/project/elite-reasoning-mcp/">View on PyPI</a> •
  <a href="https://github.com/Snehgabani/elite-reasoning-mcp/issues">Report a Bug</a>
</p>
