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

MEMGRAPH-MCP