Nami Mini: A Single-Binary AI Agent Framework Built in Rust

Most AI assistant projects you find these days are a Python package, three config files, and a prayer. Nami Mini (nami-core-mini) takes a different route: it is an advanced AI assistant and autonomous agent framework built entirely in Rust, powered by the Agent Development Kit (adk-rust) and Google’s Gemini models, and shipped as a single binary.

In this post, we’ll walk through what Nami Mini is, how its architecture is put together, and why the Rust approach matters for agent frameworks in 2026.

What Is Nami Mini?

Nami Mini combines a robust single-binary architecture with:

• Hierarchical multi-agent delegation
• Model Context Protocol (MCP) support (both Stdio and remote HTTP)
• SQLite-backed persistent memory and sessions
• Context compaction for long-running conversations
• Workspace security sandboxing for file and command execution
• A multimodal media pipeline (image, TTS, background music, video synthesis)

One cargo run gives you an interactive chat REPL, a one-shot question CLI, or a full HTTP server with SSE streaming and a web UI — all from the same codebase.

Architecture at a Glance

The project layout is refreshingly direct:

├── Cargo.toml                # Rust dependencies and workspace configuration
├── nami.json                 # Agent config, sub-agents, tools, MCP servers, CLI toggles
├── .skills/                  # Automatic skill definitions (code-reviewer, multimodal-pipeline)
├── src/
│   ├── main.rs               # CLI entrypoint and subcommand dispatcher
│   ├── agent.rs              # Agent builder, model setup, and plugin configuration
│   ├── api_client.rs         # SSE-speaking HTTP client for CLI surfaces
│   ├── cli.rs                # Interactive REPL, prompt parsing, and stream rendering
│   ├── config.rs             # Configuration structs and validation logic
│   ├── server.rs             # Axum HTTP server, static UI routes, background runs, cron
│   ├── memory.rs             # SQLite memory adapter and wiki Markdown knowledge indexer
│   ├── workspace.rs          # Security guard for file operations and sandboxing
│   ├── compaction.rs         # Context window compaction logic
│   ├── mcp.rs                # Stdio subprocess and remote HTTP MCP server managers
│   ├── grill.rs              # /grill REPL command for idea refining
│   ├── plan.rs               # /plan REPL command for task decomposition
│   ├── goal.rs               # /goal REPL command for autonomous loops
│   ├── media/                # Multimedia generation, assembly, and manifests
│   └── tools/                # Built-in toolsets (filesystem, search, fetch, weather, datetime)
├── book/                     # Comprehensive conceptual guide & architecture chapters
└── wiki/                     # Spikes, implementation plans, and feature comparisons

Everything is configuration-driven through nami.json, where you define models, system instructions, sub-agents, enabled tools, MCP servers, CLI display toggles (show_tool_call, show_tool_result, show_thinking), and media generation options.

Key Features

1. Modular Hierarchical Agent Architecture

Nami Mini uses a root agent (nami-mini) that delegates to a team of specialized sub-agents: researcher, coder, reviewer, tester, and media.

• Automatic skill injection via adk-skill loads skill definitions at startup.
• Tool delegation happens through transfer_to_agent, letting the root agent hand off a task to the right specialist mid-conversation.
• Retry & Reflection plugin (adk-retry-reflect) lets agents self-correct when a tool call fails instead of giving up — a small but meaningful reliability win.

This “router + specialists” pattern mirrors how teams of humans actually work, and writing it in Rust makes the orchestration layer predictable and fast.

2. A Rich Tool Ecosystem

Under src/tools/, Nami Mini ships with several categories of capability:

• Devtools & filesystem — sandboxed file read/write, directory traversal, and command execution, all governed by a WorkspaceGuard security layer.
• Web search & data — Google Search integration (google_search), a plain-text HTML extractor (web_fetch), date/time utilities, and weather forecasting.
• Model Context Protocol (MCP) — full support for both Stdio subprocess servers and remote streamable HTTP MCP endpoints (src/mcp.rs), so you can plug into the wider MCP ecosystem of third-party tools.

3. Persistent Memory and a Background Server

Agent state isn’t ephemeral. Nami Mini uses SQLite-backed storage (adk-session, adk-memory) for multi-turn conversations and long-term agent recall — including a wiki Markdown knowledge indexer for organizing notes into retrievable knowledge.

For serving, the serve subcommand starts an Axum-based HTTP server exposing:

• SSE streams for real-time token and tool-call updates
• A Web UI at /ui/
• Durable background runs at /api/runs
• Scheduled cron jobs at /api/cron

The CLI itself has two modes:

# Interactive chat with configurable output visibility
cargo run -- chat

# Single question, clean answer-only output
cargo run -- ask "Explain how Nami Mini works"

# Start the HTTP server
cargo run -- serve --port 8080

4. Advanced Context Compaction

Long sessions bloat the context window, which degrades quality and inflates token costs. Nami Mini’s compaction.rs performs post-run conversation history compaction, summarizing and pruning past turns so the agent stays sharp across extended interactions. Combined with persistent memory, this means the agent can carry a relationship with a user across days rather than being reset at every prompt.

5. Multimodal Media Pipeline

Perhaps the most distinctive feature: Nami Mini can generate media, not just text. Its media/ module and src/tools/media.rs orchestrate specialized Gemini models for:

• Images (generate_image)
• Voiceover audio / TTS (generate_tts)
• Background music (generate_music, powered by Lyria)
• Video clips (generate_video via the Gemini Interactions API)
• Audio/video assembly (assemble_audio_video)

Give it a story or a topic, and the media sub-agent can produce a narrated, scored, assembled piece of content — a mini production pipeline inside a single binary.

Interactive Workflow Commands

Beyond plain chat, Nami Mini adds three REPL commands designed for serious thinking work:

Command	Purpose
/grill	Interactively refine and pressure-test an idea
/plan	Decompose a task into structured steps
/goal	Kick off autonomous loops toward a defined goal

These are small additions, but they push the CLI from “chat wrapper” toward a genuine agentic workstation.

Why Rust?

Choosing Rust for an agent framework is a deliberate statement:

1. Single-binary deployment. No Python virtualenvs, no dependency hell — ship one artifact with cargo build --release.
2. Predictable performance. The orchestration layer (SSE streaming, tool dispatch, gateway routing) benefits from zero-GC latency and cheap concurrency.
3. Type safety across a large surface. With config structs, plugin traits, and a dozen modules, the borrow checker catches integration bugs that would surface at runtime in a dynamic language.
4. Memory safety for a long-lived server. The serve mode runs for days; memory bugs are not an option.

Combined with adk-rust, which brings Google’s Agent Development Kit concepts (agents, tools, plugins, sessions, memory) to Rust, Nami Mini shows that the ADK mental model translates cleanly outside of Python.

Getting Started

Prerequisites:

• A Rust toolchain matching the Cargo.toml (2024 edition)
• A Google Gemini API key, configured in .env or environment variables

Then:

1. Clone the repository.
2. Copy .env.example to .env and add your API key.
3. Adjust nami.json to your liking (models, tools, MCP servers, CLI toggles).
4. Run cargo run -- chat and start talking.

The repo also ships a book/ directory with a conceptual guide and architecture chapters, plus a wiki/ with spikes, implementation plans, and feature comparisons — refreshingly thorough documentation for a young project.

Final Thoughts

Nami Mini is a compelling proof point: a modern agent framework doesn’t have to be a heavyweight Python platform. With hierarchical delegation, MCP integration, SQLite memory, context compaction, a sandboxed workspace, and a full multimodal media pipeline packed into one Rust binary, it’s a project worth watching — and a great reference implementation if you’re building your own agent stack.

Check it out on GitHub: github.com/anoochit/nami-core-mini