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

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:

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: current project state, changes since creation, and roadmap

• docs/getting_started.md: fastest path to a working local run and MCP server

• docs/operator_guide.md: full system overview, operations, and best practices

• docs/developer_custom_graphs.md: Python API usage, custom graph design, and node payload reference

• docs/codex_mcp_usage.md: how Codex should use this MCP for large-app planning, memory, and checkpointed execution

• examples/plan_large_app.py: example of generating a large-app blueprint and run programmatically