modus-ai 0.4.0

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

Install options

The core install is fully functional — chat, memory with keyword search, tools, MCP, workflows, deploy, and observability (without OTel). Heavy optional pieces are extras:

Embedding calls (OpenAI/Gemini/Ollama) work without any extra — the SDKs are core. Without vector, Memory(embedding=...) falls back to keyword search and logs the missing index — it never raises. CI enforces that import modus and the full test suite pass in a core-only install.

Providers & integrations

15+ providers out of the box — pass a string to Agent(provider=...):

Embeddings: OpenAIEmbedding, GeminiEmbedding, OllamaEmbedding, VoyageEmbedding, MistralEmbedding, AzureEmbedding, NoopEmbedding — or Memory(embedding="voyage") with the new string shortcuts. Full reference: the providers guide.

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

Key architecture

• Monorepo, single package: pip install modus-ai
• Memory: OKF .md files + YAML frontmatter → FTS5 + pluggable vector search (LanceDB / pgvector / Chroma)
• 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

Current status

Alpha → v0.3.0. Agent, memory, actions, safety, planner, vision, speech, skills, providers (15+), orchestration, deploy, observability, structured outputs, and durable workflows are implemented and tested — 785 offline tests + 34 real-API live tests, ~86.5% coverage, mypy-clean, ruff-clean.

License

MIT