modus-ai 0.2.1

Modular AI agent framework

Modus — Modular AI agents. Composable by design.



Modus is an open-source modular AI agent framework that provides reusable components
for building, orchestrating, and deploying autonomous AI systems.

Memory systems. Planning loops. Safety guards. Tool execution. MCP integration.
All packaged as swappable modules with clear protocol boundaries.

Why Modus?

Building AI agents today means reinventing the same infrastructure every time: memory systems, planning loops, safety guards, tool execution, perception pipelines. Every framework forces you into a monolithic agent runtime where swapping one piece means rewriting half the system.

Modus takes the opposite approach.

Each capability is a self-contained module with a well-defined protocol interface. Swap memory backends without touching the planner. Change planning strategies without rewriting the action layer. Add safety policies without forking the codebase.

No vendor lock-in. No monolithic runtimes. Just composable building blocks.

Quick start

pip install modus-ai

from modus import Agent
from modus.memory import Memory
from modus.memory.embeddings import GeminiEmbedding, OpenAIEmbedding

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    provider="openai",
    memory=Memory("./data", embedding=OpenAIEmbedding()),
)

# Memory context auto-injected, Chat auto-managed
response = agent.run("What do I know about Project Phoenix?")

# Gemini embeddings (uses the GEMINI_API_KEY env var)
gemini_memory = Memory("./data", embedding=GeminiEmbedding(model="gemini-embedding-001"))

What's built

Module	Features	Status
Agent	ReAct loop, Chat history, Memory injection, Tool calling, Event hooks, session persistence, trace IDs, dry-run	✅
Memory	OKF .md files, PyYAML frontmatter, FTS5 keyword search, LanceDB vector search, Hybrid scoring, LLM analysis, entity extraction, TTL + importance eviction, dedup gate, Dreaming, consolidation, tenant isolation, concurrent + cross-process safe writes	✅
Actions	Local tool registry, @tool decorator, MCP stdio/HTTP transport with handshake + auth headers, argument validation, result compaction, caching, transient-only retry, timeout, parallel execution, middleware, authorization	✅
Safety	3-tier interceptor (deterministic rules, HITL, LLM review), per-iteration and global call limits	✅
Planner	SHORT_CIRCUIT, REACT, TREE_OF_THOUGHT with parallel branch execution	✅
Vision	OpenAI, Anthropic, Gemini, Ollama, Tesseract providers; SSRF guard, thumbnailing, caching, multi-modal memory	✅
Skills	Package registry (tools + prompts + concepts), path-traversal protection	✅
Providers	OpenAI (incl. Groq/OpenRouter/Together/Ollama), Anthropic, Gemini with tool calling; retry/backoff with jitter + Retry-After	✅
Orchestration	Workflow graph engine, dependency resolution, conditional routing, loops, HITL, state persistence, validation, hooks, async, sub-workflows, Mermaid export, context isolation, Team	✅
Deploy	FastAPI webhook server (Bearer auth, CORS, rate limit, body caps), APScheduler (cron + interval)	✅
Observability	Trace IDs, JSON structured logs, optional OpenTelemetry spans	✅

Key architecture

• Monorepo, single package: pip install modus-ai
• Memory: OKF .md files + YAML frontmatter → FTS5 + LanceDB hybrid search
• Actions: Plugin local tools or connect MCP servers (stdio or HTTP)
• ReAct loop: Agent detects LLM tool calls, executes in parallel, feeds results back
• Chat: Token-budget conversation history, auto-summarized overflow
• All modules are standalone: from modus.memory import Memory — works without Agent

Example: Tools

from modus import Agent
from modus.actions import tool

@tool(name="get_weather", description="Get weather for a city", parameters={
    "type": "object",
    "properties": {"city": {"type": "string"}},
    "required": ["city"],
})
def get_weather(city: str) -> str:
    return f"Sunny, 25°C in {city}"

agent = Agent(name="WeatherBot", instructions="Use tools to answer questions.")
agent.actions.register(get_weather)

response = agent.run("What is the weather in Tokyo?")

Example: MCP server

agent.actions.connect(
    "filesystem",
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem", "."],
)
# Tools auto-discovered and available in the ReAct loop

Example: Workflow with multiple agents

from modus.orchestration import Workflow, Step

workflow = Workflow(steps={
    "classify": Step(agent=classifier, next={"billing": "resolve", "tech": "escalate"}),
    "resolve": Step(agent=resolver, retry=2, timeout=30),
    "respond": Step(agent=responder, depends_on=["resolve", "escalate"]),
})

result = workflow.run("I was charged twice")

Documentation

Section	Description
Architecture	Block architecture and lifecycle
Memory Guide	OKF concepts, storage, retrieval, API reference
Actions Guide	MCP servers, tool execution, ReAct loop
Logging & Observability	Trace IDs, structured logs, per-module tuning
Security Model	Trust boundaries, subprocess isolation
Protocol Reference	Module interface contracts
Contributing	Development guide and RFC process
Roadmap	Upcoming milestones

Current status

Alpha. Agent, memory, actions, safety, planner, vision, skills, providers, orchestration, deploy, and observability are implemented and tested (543 tests, ~82% coverage, mypy-clean, ruff-clean).

License

MIT