Elite Reasoning

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

Give coding agents a compact, evidence-gated workflow layer with trusted memory and local release verification.

Quick Start • Features • Use Cases • Architecture • Core Tools • Config • Security • Contributing

---

Why Elite Reasoning?

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

It's a Model Context Protocol 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

pip install elite-reasoning-mcp

For an isolated CLI installation:

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):

{
  "mcpServers": {
    "elite-reasoning": {
      "command": "elite-reasoning-mcp",
      "args": [],
      "env": {
        "ELITE_BRAIN_DIR": "~/.elite-reasoning/brain",
        "ELITE_TOOL_PROFILE": "core"
      }
    }
  }
}

Cursor (.cursor/mcp.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):

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):

## ⚡ 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:

Core Pipeline (3)

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

Workflow, Release & Eval (8)

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

Quality & Anti-Patterns (6)

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

Decision Making (6)

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

Risk Analysis (5)

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

Confidence & Calibration (3)

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

Memory & Knowledge Graph (5)

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

Goals & Benchmarks (7)

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

Learning & Autonomy (12)

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

Quantitative Reasoning (5)

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

Collaboration (5)

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

Natural Language Verbs (6)

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

Hypothesis & Prospective (5)

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

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 and docs/examples/team-memory.example.json. Keep credentials in process environment variables or an OS keychain, not in JSON.

Development Setup

# 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

# 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, not public issues.

For the next tracking and monitoring layer, see the Elite Telemetry Roadmap.

---

🤝 Contributing

Contributions are welcome. Start with CONTRIBUTING.md, GOVERNANCE.md, and the security boundaries in 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:

• feat: — New features
• fix: — Bug fixes
• chore: — Maintenance
• docs: — Documentation

---

📄 License

MIT © Sneh Gabani

---

_{Built for the AI-native developer workflow}

Star us on GitHub • View on PyPI • Report a Bug