Skip to main content
Glama

sovereign-exoself-mcp

Local MCP server for personal AI Council. Routes tasks through manager, worker, critic, synthesizer, and archivist with fast/review/full paths. Uses SQLite memory with WAL and FTS5. Supports mock, Ollama, and OpenRouter providers.

Architecture

flowchart LR
  C[MCP stdio client] --> T[3 tools]
  T --> O[Council Router]
  O --> M[Manager<br/>granite3.3:2b]
  M -->|fast| W[Worker<br/>qwen2.5-coder:7b]
  M -->|review| W
  M -->|full| W
  W -->|review| CR[Critic<br/>qwen2.5-coder:7b]
  CR -->|reject| W
  CR -->|approve| S[Synthesizer<br/>granite3.3:2b]
  S -->|full| A[Archivist<br/>granite3.3:2b]
  S --> R[Result]
  A --> R

Related MCP server: orchestrator-mcp

Model Configuration (Config B)

Role

Model

Rationale

Manager

granite3.3:2b

Fast routing decisions

Worker

qwen2.5-coder:7b

Quality code execution

Critic

qwen2.5-coder:7b

Reliable code review

Synthesizer

granite3.3:2b

Fast result merging

Archivist

granite3.3:2b

Fast memory extraction

Benchmark: 1504ms avg, 3428ms P95, 100% success rate, 0 timeouts.

Quick Start

Requirements: Ubuntu/Linux, Python 3.14, uv.

cd /home/hat/AionUI/sovereign-exoself-mcp
bash scripts/install.sh
bash scripts/smoke_test.sh --mock

--mock mode requires no API key and is useful for offline validation. For real inference, run the server directly with a provider (see below). scripts/generate_client_configs.py auto-generates host snippets (dist/) that enable a real provider: ollama by default, openrouter when OPENROUTER_API_KEY is present.

Ollama Mode

# Pull required models
ollama pull granite3.3:2b
ollama pull qwen2.5-coder:7b

# Run with Ollama
SOVEREIGN_PROVIDER_MODE=ollama \
uv run python -m sovereign_exoself_mcp

OpenRouter Mode

# Secrets are environment-only: store the key in the gitignored `.env` file
echo "OPENROUTER_API_KEY=sk-or-v1-..." >> .env

SOVEREIGN_PROVIDER_MODE=openrouter \
uv run python -m sovereign_exoself_mcp

Council Routes

Fast Path (Default)

Manager → Worker → Result. Used for simple questions, facts, quick analysis.

Review Path

Manager → Worker → Critic → Synthesizer → Result. Used for code changes, architecture decisions.

Full Council

Manager → Worker → Critic → Synthesizer → Archivist → Result. Used for complex tasks requiring memory.

API Tools

council_run

{
  "task": "Review and improve the configuration loader.",
  "mode": "auto",
  "budget": "low",
  "worker_profile": null,
  "needs_memory": null,
  "max_rounds": null,
  "route_override": null
}

Mode values: auto (manager decides), code, analysis, decision. As a shorthand, mode also accepts fast, review, or full to force a route directly. An explicit route_override (fast/review/full) always wins when provided.

Response includes: run_id, status, route, models, result, metrics, memory_updates, warnings

memory_manage

{
  "action": "search",
  "query": "design decisions"
}

Actions: search, store, list, delete, export, profile

system_status

Returns health, provider mode, model mapping, prompt versions, active runs, Ollama status.

Changing Models

# Environment variables
export SOVEREIGN_OLLAMA_WORKER_MODEL=qwen3:8b
export SOVEREIGN_OLLAMA_MANAGER_MODEL=gemma2:2b

# Or config file
cp config/council.example.yaml config/council.yaml
# Edit config/council.yaml

Worker Profiles

Profile

Purpose

code_engineer

Code implementation, debugging, refactoring

system_engineer

Infrastructure, DevOps, system design

researcher

Information gathering, analysis

technical_writer

Documentation, prose

planner

Task decomposition, project planning

general_operator

Default fallback

Running Benchmark

# Mock benchmark
python benchmarks/benchmark.py --mode mock

# Live benchmark (requires Ollama with models)
OLLAMA_TEST_MODEL=qwen2.5-coder:7b python benchmarks/benchmark.py --mode ollama

System Status

# Via MCP tool
system_status({})

# Via CLI
uv run python -c "import asyncio; from sovereign_exoself_mcp.providers import probe_ollama; print(asyncio.run(probe_ollama('http://127.0.0.1:11434', 5)))"

Rollback

  1. Set SOVEREIGN_PROVIDER_MODE=mock

  2. Remove new environment variables

  3. Revert code changes

Adding Worker Profiles

  1. Create src/sovereign_exoself_mcp/prompts/profiles/<name>.txt

  2. Add to PROFILES list in prompts.py

  3. Use in requests: {"worker_profile": "<name>"}

Environment Variables

See .env.example for all available settings.

Documentation

Testing

# Run all tests
python -m pytest tests/ -v

# Run specific test suite
python -m pytest tests/unit/test_prompts.py -v
python -m pytest tests/unit/test_router.py -v
python -m pytest tests/unit/test_schemas.py -v

License

MIT

Available Tools

3 tools
council_runD

Run the bounded personal council.

Inputs: task (required), mode, budget, max_rounds, +5 more. Returns: object

memory_manageB

Search, store, list, delete, export, or profile memory.

Inputs: action (required), kind, limit, query, +2 more. Returns: object

system_statusA

Return local health without calling a provider.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct domain: running a council, managing memory, and checking system status. There is no overlap in functionality, so an agent can easily select the right tool.

    Naming Consistency4/5

    Tools use a consistent underscore-separated, lowercase pattern. The first two are noun-verb compounds (council_run, memory_manage), while system_status is a noun-noun compound, creating a minor inconsistency, but it's still readable and recognizable.

    Tool Count5/5

    With only three tools, the server is tightly focused on the core functions of a personal exoself: decision-making (council), memory, and health. The count is small but each tool has a clear purpose and fits within the typical well-scoped range.

    Completeness4/5

    The memory_manage tool covers a full range of memory operations, and council_run covers the main action for the council. A possible gap is the lack of configuration or lifecycle management for the council, but for a bounded personal council, this may be sufficient, so the core workflows are covered.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers