# How to Run AI Agents with ai-memory CLI Commands > Learn to run AI agents like Claude and Codex using ai-memory CLI commands. Start the server with `ai-memory serve` and launch agents with `ai-memory run ` for seamless orchestration and interaction persistence. - Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory) - Tags: how-to-guide - Published: 2026-09-01 --- **Use `ai-memory run ` 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`](https://github.com/akitaonrails/ai-memory/blob/main/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. ```bash # 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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/run.rs). The `ai-memory run ` command creates a local checkout, establishes an HTTP connection via the `HttpClient` defined in [`crates/ai-memory-cli/src/http_client.rs`](https://github.com/akitaonrails/ai-memory/blob/main/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 `** – Selects a specific LLM provider if configured - **`--workspace `** – Scopes the session to a specific workspace - **`--project `** – Isolates the session under a named project - **`--executable `** – Runs a custom executable inside the managed workstream ```bash # 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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/resume.rs): ```bash ai-memory resume ``` 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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/search.rs), queries this index: ```bash # 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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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 ` 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 ` 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 ` 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 ` 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.