# Agent System

A durable multi-agent orchestrator with:
- explicit run graphs and checkpoint/resume
- orchestrator-controlled parallel delegation
- bounded research swarm execution
- coding, review, repair, CI, and approval loops
- project memory in backing stores exposed through MCP resources and tools
- a real SQLite vector index for memory retrieval
- a pluggable external research backend with Tavily support

## Scope
This implementation targets the MCP `2025-11-25` spec baseline with the official Python MCP SDK and a `FastMCP` server for the memory surface. For local development it runs over `stdio`. For remote deployment, see `docs/remote_auth.md`.

## Layout
- `app/runtime`: run state, scheduler, orchestrator loop, checkpointing
- `app/planner`: planning and graph revision helpers
- `app/agents`: node executors for research, code, review, repair, CI, synthesis, approval
- `app/memory`: SQLite-backed memory, retrieval, and artifact index
- `app/mcp_server`: `FastMCP` resources, tools, prompts, and server entrypoint
- `tests`: acceptance and unit coverage

## Local usage
```bash
uv sync --group dev
uv run pytest
uv run agent-system-mcp
```

## Retrieval and research backends
- Memory entries are indexed into a local SQLite vector table using `sqlite-vec`.
- The default embedding provider is `auto`: it prefers a real `sentence-transformers` model and falls back to the deterministic hash provider only if the model cannot load.
- Research uses an in-memory corpus backend when a node provides `inputs.corpus`.
- If `TAVILY_API_KEY` is set, corpus-free research nodes can use the Tavily backend for external web research.
- If no corpus and no Tavily key are available, research returns bounded empty findings instead of inventing sources.

## Embedding configuration
- `AGENT_SYSTEM_EMBEDDING_PROVIDER=auto|sentence-transformers|hash`
- `AGENT_SYSTEM_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2`
- `AGENT_SYSTEM_EMBEDDING_CACHE_DIR=/path/to/cache`
- `AGENT_SYSTEM_EMBEDDING_LOCAL_ONLY=true|false`

Example:
```bash
AGENT_SYSTEM_EMBEDDING_PROVIDER=sentence-transformers uv run agent-system create-run "improve scheduler"
```

## Local transport
Development uses the MCP `stdio` transport.

## Remote deployment
Remote deployment is intentionally documentation-only in v1. The server documents an OAuth 2.1-compatible consent path and keeps local `stdio` as the default development mode.

## Full documentation
- [state.md](state.md): current project state, changes since creation, and roadmap
- [docs/getting_started.md](docs/getting_started.md): fastest path to a working local run and MCP server
- [docs/operator_guide.md](docs/operator_guide.md): full system overview, operations, and best practices
- [docs/developer_custom_graphs.md](docs/developer_custom_graphs.md): Python API usage, custom graph design, and node payload reference
- [docs/codex_mcp_usage.md](docs/codex_mcp_usage.md): how Codex should use this MCP for large-app planning, memory, and checkpointed execution
- [examples/plan_large_app.py](examples/plan_large_app.py): example of generating a large-app blueprint and run programmatically