How to Run AI Agents with ai-memory CLI Commands

Use ai-memory run <agent> to launch AI agents (Claude, Codex, Kiro, etc.) after starting the background server with ai-memory serve, which orchestrates the session via MCP and persists interactions to a searchable wiki.

The ai-memory CLI from the akitaonrails/ai-memory repository provides a dedicated command-line interface for running and managing AI agent workflows. It handles repository checkouts, agent orchestration through the Model Context Protocol (MCP), and automatic documentation of sessions without requiring custom integration code.

Starting the MCP Server

Before running any agents, you must start the background server using the command defined in crates/ai-memory-cli/src/commands/serve.rs. The ai-memory serve command launches the server on 127.0.0.1:49374 by default, initializes the SQLite store, and listens for MCP requests from agents.

# Start the server in the background

ai-memory serve &

The server maintains the state for all agent sessions and manages the wiki/ directory where interactions are stored.

Launching Agent Sessions with ai-memory run

The core functionality for running agents resides in crates/ai-memory-cli/src/commands/run.rs. The ai-memory run <agent> command creates a local checkout, establishes an HTTP connection via the HttpClient defined in crates/ai-memory-cli/src/http_client.rs, and executes the specified agent.

Key flags control session behavior:

• --new – Forces a fresh checkout instead of reusing an existing session
• --yolo – Skips the interactive prompt and runs the agent immediately
• --model <model> – Selects a specific LLM provider if configured
• --workspace <name> – Scopes the session to a specific workspace
• --project <name> – Isolates the session under a named project
• --executable <path> – Runs a custom executable inside the managed workstream

# Run Claude agent on current repository

ai-memory run claude

# Run Codex with fresh checkout, skipping prompts

ai-memory run codex --new --yolo

# Run a custom tool with a new session

ai-memory run --new my-tool --executable ./my_tool.sh

Managing Sessions and Checkouts

The CLI automatically detects existing sessions matching the current repository. Without the --new flag, ai-memory run attaches to the existing checkout and continues the conversation. To resume a specific stopped session, use the command implemented in crates/ai-memory-cli/src/commands/resume.rs:

ai-memory resume <RUN_ID>

The session state and repository checkout persist between runs, allowing agents to maintain context across multiple invocations.

Searching and Retrieving Results

All agent interactions are automatically recorded as durable markdown pages under the wiki/ directory and indexed using FTS5 for full-text search. The ai-memory search command, implemented in crates/ai-memory-cli/src/commands/search.rs, queries this index:

# Search wiki for specific terms

ai-memory search "memory consolidation"

# Display specific page details

ai-memory show src/agents/claude/notes.md

Core CLI Architecture

The CLI entry point in crates/ai-memory-cli/src/main.rs sets up argument parsing using Clap and dispatches to appropriate sub-commands. Global flags and the shared CLI structure are defined in crates/ai-memory-cli/src/cli.rs, including options for the data directory, workspace, and project scoping.

The HttpClient in crates/ai-memory-cli/src/http_client.rs handles all communication with the MCP server, managing bearer-token injection and JSON marshalling for RPC calls.

Summary

• Start the server with ai-memory serve before running any agents to enable MCP communication on 127.0.0.1:49374
• Use ai-memory run <agent> with flags like --new and --yolo to control checkout behavior and skip interactive prompts
• Sessions automatically persist as markdown wiki pages indexed by FTS5 for full-text search
• Resume existing sessions with ai-memory resume <run-id> or let the CLI auto-detect matching repositories
• Run custom executables using the --executable flag while maintaining ai-memory's session management

Frequently Asked Questions

How do I run an AI agent without interactive prompts?

Use the --yolo flag when running ai-memory run. This skips the interactive confirmation prompt and executes the agent immediately, which is useful for automation scripts or when you trust the agent's configuration.

Can I use multiple LLM providers with ai-memory?

Yes. The --model <model> flag allows you to select specific LLM providers if configured in your environment. The CLI passes this selection to the agent during session initialization via the MCP protocol.

Where are agent interactions stored?

Interactions are stored as markdown pages in the wiki/ directory within your repository. The background server maintains a SQLite database with FTS5 indexing that enables full-text search through the ai-memory search command.

How do I resume a previous agent session?

Use ai-memory resume <RUN_ID> to reattach to a specific session, or simply run the original ai-memory run command again without the --new flag. The CLI detects existing checkouts matching your current repository and reconnects to the active session automatically.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}