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

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

• Council Architecture
• Council Prompts
• Routing and Execution
• Model Configuration
• Migration Guide
• Troubleshooting

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