MiMinions

An agentic framework built on pydantic-ai with Model Context Protocol (MCP) server support, a generic tool system, three-tier memory, and local-first workspaces.

📖 Full documentation: miminions.ai

Features

• Minion agent — an async, LLM-powered agent on pydantic-ai, defaulting to OpenRouter (with OpenAI, Anthropic, Gemini, and an offline test model also selectable).
• Generic tool system — turn a typed Python function into an agent-callable tool with an auto-derived JSON schema; no boilerplate.
• MCP integration — connect to MCP servers and load their tools alongside your own functions.
• Three-tier memory — a chronological session log (HISTORY.md), stable workspace facts (MEMORY.md), and a cross-workspace SQLite vector store, with an LLM distiller that promotes insights across tiers.
• Vector memory — SQLiteMemory with semantic, keyword, full-text, metadata, regex, hybrid, and date-range search, embeddings via fastembed (ONNX — no PyTorch/CUDA).
• Workspaces — a node/rule graph plus an on-disk layout (prompt/, memory/, skills/, sessions/, data/) that drives each agent's context.
• CLI — manage agents, tasks, knowledge, workspaces, and an interactive chat from the miminions command; state persists under ~/.miminions/.
• Local data manager — content-addressable (SHA-256) storage with deduplication, a master index, and an append-only transaction log.
• Async-first — full asynchronous operation throughout.

Installation

pip install miminions

Or with uv:

uv add miminions

Requires Python 3.12+. SQLite vector memory is an optional extra (it adds fastembed, sqlite-vec, and pysqlite3):

pip install miminions[sqlite]   # or miminions[all]

The agent uses OpenRouter by default — set your key before running:

export OPENROUTER_API_KEY="sk-or-..."

Quick Start

A first agent with a custom tool

import asyncio
from miminions.agent import create_minion

async def main():
    agent = create_minion("MyAgent")

    def add(a: int, b: int) -> int:
        return a + b

    agent.register_tool("add", "Add two numbers", add)

    # The model decides when to call the tool.
    reply = await agent.run("What is 3 + 7?")
    print(reply)

asyncio.run(main())

Want a different model? Pass a provider (or a pydantic-ai model directly):

agent = create_minion("MyAgent", provider="anthropic")   # or "openai", "gemini"
agent = create_minion("MyAgent", provider="test")          # offline, no API key

An agent with vector memory

from miminions.memory.sqlite import SQLiteMemory
from miminions.agent import create_minion

agent = create_minion("Assistant", memory=SQLiteMemory("agent.db"))

# store_knowledge / recall_knowledge require an attached memory backend.
agent.store_knowledge("Python is a high-level language", metadata={"topic": "python"})
print(agent.recall_knowledge("What language is Python?"))

With memory attached, the agent also gains a built-in ingest_document tool that chunks and stores .pdf/.txt/.md files. Requires the [sqlite] extra.

Loading tools from an MCP server

from mcp import StdioServerParameters
from miminions.agent import create_minion

agent = create_minion("MyAgent")
await agent.connect_mcp_server(
    "math", StdioServerParameters(command="python", args=["math_server.py"])
)
await agent.load_tools_from_mcp_server("math")
# ...
await agent.cleanup()

CLI Usage

After install, the miminions command is available (a default workspace and agent are created under ~/.miminions/ on first run):

miminions --help
python -m miminions --help        # equivalent

Command groups:

Group	What it does
chat	Interactive chat with a workspace agent; distills memory on exit
prompt	One-shot prompt to a workspace agent
agent	Create/manage agents and run/inspect their tools
task	Create and track tasks
knowledge	A versioned knowledge base
workspace	Manage workspaces, their nodes, rules, and on-disk files
execution	Register tools and record tool runs in execution sessions
auth	Local sign-in, public-access mode, and config

# Start an interactive chat (resume with --session <id>)
miminions chat start

# One-shot prompt
miminions prompt ask "Summarize today's standup notes"

# Agents
miminions agent add --name "Researcher" --description "Finds and summarizes sources"
miminions agent list

# Workspaces
miminions workspace add --name "Demo" --sample --init-files
miminions workspace list

The workflow command group exists in the codebase but is not yet enabled. The --async flag on miminions agent run is currently a placeholder.

See the CLI reference for every subcommand.

Documentation

Topic
Getting Started	Install, first agent, and the CLI
Agent	The Minion API
Memory	Three-tier and vector memory
Context Builder	System-prompt assembly
Tools	@tool, GenericTool, MCP
Workspaces	Nodes, rules, on-disk layout
Tasks & Workflows	TaskRuntime and tracing
Data Management	LocalDataManager
Gateway Runtime	Channels, bus, cron

For a map of the source tree and module status, see STRUCTURE.md. Runnable examples live in examples/.

Development

git clone https://github.com/MiMinions-ai/MiMinions.git
cd MiMinions
pip install -e ".[dev]"

Run the tests:

pytest tests/                 # everything
pytest tests/unit/            # unit
pytest tests/integration/     # integration
pytest tests/e2e/             # end-to-end

Publishing

pyproject.toml is the single source of truth for packaging. Build and publish with uv:

uv build
uv publish
# TestPyPI:
uv publish --publish-url https://test.pypi.org/legacy/

Build a standalone CLI binary:

bash deploy/build_cli.sh

Contributing

Contributions are welcome — see CONTRIBUTING.md and the Code of Conduct. Feature work targets the development branch.

License

MIT — see LICENSE.