# Complete Guide to ai-memory CLI Subcommands for Server, Wiki, and Session Management

> Master ai-memory CLI subcommands for server, wiki, and session management. Explore 28+ modules for efficient operation and integration. Get the complete guide now.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-08-28

---

**The ai-memory CLI exposes 28+ subcommands for managing server lifecycle, wiki content, session handoffs, and agent integrations, all implemented as individual modules in `crates/ai-memory-cli/src/commands/`.**

The **ai-memory** project provides a Rust-based memory server with a comprehensive command-line interface. Whether you're bootstrapping a new wiki, managing session handoffs between agents, or maintaining the underlying datastore, the CLI in `akitaonrails/ai-memory` offers fine-grained control over every operation.

## Server Lifecycle Subcommands

### Start and Monitor the Server

The `serve` subcommand launches the ai-memory server with configurable transport and optional web UI:

```bash
ai-memory serve --transport http --bind 127.0.0.1:49374 --enable-web

```

Implementation resides 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). This handles HTTP/MCP transport initialization and the web interface.

Verify server health with `status`:

```bash
ai-memory status

```

This prints bind address, data directory, and connected projects—implemented in [`crates/ai-memory-cli/src/commands/status.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/status.rs).

### Datastore Maintenance

| Subcommand | Purpose | Source File |
|------------|---------|-------------|
| `reindex` | Rebuilds SQLite FTS5 index after bulk edits | [`crates/ai-memory-cli/src/commands/reindex.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/reindex.rs) |
| `data-purge` | Removes temporary files and stale caches | [`crates/ai-memory-cli/src/commands/data_purge.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/data_purge.rs) |
| `reset` | **Destructive**: clears all data for a workspace | [`crates/ai-memory-cli/src/commands/reset.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/reset.rs) |
| `purge-project` | Deletes entire project including wiki and observations | [`crates/ai-memory-cli/src/commands/purge_project.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/purge_project.rs) |

Use `reindex` after manual markdown edits in the wiki directory to ensure the FTS5 search index stays synchronized.

## Project Bootstrapping and Agent Integration

### Initialize from Existing Codebases

The `bootstrap` command seeds a fresh wiki by analyzing Git history, README files, and documentation. It requires a configured LLM provider:

```bash
export AI_MEMORY_SERVER_URL="http://127.0.0.1:49374"
ai-memory bootstrap --dry-run  # Preview import

ai-memory bootstrap            # Execute import

```

Source: [`crates/ai-memory-cli/src/commands/bootstrap.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/bootstrap.rs)

### Install Routing and Skills

Four related commands configure agent integration:

- **`install-instructions`** ([`install_instructions.rs`](https://github.com/akitaonrails/ai-memory/blob/main/install_instructions.rs)): Installs the routing snippet **and** Agent Skills by default
- **`install-skills`** ([`install_skills.rs`](https://github.com/akitaonrails/ai-memory/blob/main/install_skills.rs)): Skills only—use when routing snippet already exists
- **`install-hooks`** ([`install_hooks.rs`](https://github.com/akitaonrails/ai-memory/blob/main/install_hooks.rs)): Deploys lifecycle hooks (capture, pre-compact) to [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml)
- **`install-mcp`** ([`install_mcp.rs`](https://github.com/akitaonrails/ai-memory/blob/main/install_mcp.rs)): Adds MCP client configuration for specific agents (Claude, Codex, Devin)

```bash

# Typical first-time setup

ai-memory bootstrap
ai-memory install-instructions

```

## Wiki Content Management Subcommands

### CRUD Operations for Pages

| Operation | Command | Implementation |
|-----------|---------|----------------|
| Create/Update | `write-page` | [`crates/ai-memory-cli/src/commands/write_page.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/write_page.rs) |
| Read | `read-page` | [`crates/ai-memory-cli/src/commands/read_page.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/read_page.rs) |
| Delete | `delete-page` | [`crates/ai-memory-cli/src/commands/delete_page.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/delete_page.rs) |

Example workflow:

```bash

# Write durable documentation

ai-memory write-page notes/quick-tip.md <<<"Tip: always run `cargo fmt` before committing."

# Verify content

ai-memory read-page notes/quick-tip.md

# Remove if obsolete

ai-memory delete-page notes/quick-tip.md

```

### Search and Embedding

The `search` command (aliased as `query`) performs FTS5-based retrieval with optional vector and explanation flags:

```bash
ai-memory search "cargo fmt" --explain

```

For vector-based semantic search, explicitly trigger embedding:

```bash
ai-memory embed

```

Source for `search`: [`crates/ai-memory-cli/src/commands/search.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/search.rs)  
Source for `embed`: [`crates/ai-memory-cli/src/commands/embed.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/embed.rs)

## Session and Handoff Workflow Commands

### Handoff Lifecycle

Handoffs enable state transfer between agent sessions:

| Stage | Command | MCP Equivalent | Source |
|-------|---------|----------------|--------|
| Create | `handoff-begin` | `memory_handoff_begin` | [`handoff_begin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/handoff_begin.rs) |
| Consume | `handoff-accept` | `memory_handoff_accept` | [`handoff_accept.rs`](https://github.com/akitaonrails/ai-memory/blob/main/handoff_accept.rs) |
| Abort | `handoff-cancel` | `memory_handoff_cancel` | [`handoff_cancel.rs`](https://github.com/akitaonrails/ai-memory/blob/main/handoff_cancel.rs) |

```bash

# Session A creates handoff

ai-memory handoff-begin --summary "Investigate the recent cargo-fmt failures."

# Session B (later) consumes it

ai-memory handoff-accept

```

### Session and Project Mobility

- **`move-session`** ([`move_session.rs`](https://github.com/akitaonrails/ai-memory/blob/main/move_session.rs)): Reattaches a session and its observations to a different project
- **`move-project`** ([`move_project.rs`](https://github.com/akitaonrails/ai-memory/blob/main/move_project.rs)): Renames or relocates a project while preserving all content

## Auto-Improvement and Curation

### Automated Quality Pipelines

```bash

# Run improvement analysis on latest session

ai-memory auto-improve

# Generate human-readable report

ai-memory auto-improve-report > improve-suggestions.txt

```

- [`auto_improve.rs`](https://github.com/akitaonrails/ai-memory/blob/main/auto_improve.rs): Triggers LLM-based review of completed sessions
- [`auto_improve_report.rs`](https://github.com/akitaonrails/ai-memory/blob/main/auto_improve_report.rs): Formats suggestions for human review

### Manual Curation

- **`curator`** ([`curator.rs`](https://github.com/akitaonrails/ai-memory/blob/main/curator.rs)): Manually runs consolidation on selected pages
- **`checkpoints`** ([`checkpoints.rs`](https://github.com/akitaonrails/ai-memory/blob/main/checkpoints.rs)): Lists or manipulates session checkpoints from LLM-driven consolidation

## Backup, Restore, and Portability

### Data Protection

```bash

# Create compressed archive of entire data directory

ai-memory backup > ai-memory-backup-$(date +%Y%m%d).tar.gz

# Restore (overwrites current datastore)

ai-memory restore < backup-file.tar.gz

```

- [`backup.rs`](https://github.com/akitaonrails/ai-memory/blob/main/backup.rs): Dumps wiki + SQLite to tarball
- [`restore.rs`](https://github.com/akitaonrails/ai-memory/blob/main/restore.rs): Overwrites current data with backup contents

## Authentication and Shell Integration

### Provider Credentials

Manage LLM provider authentication:

```bash
ai-memory auth login openai
ai-memory auth status

```

Implementation: [`crates/ai-memory-cli/src/commands/auth.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/auth.rs)

### Shell Completions

Generate tab-completion scripts for your shell:

```bash
ai-memory completions bash > /etc/bash_completion.d/ai-memory
ai-memory completions zsh > ~/.zsh/completions/_ai-memory

```

Source: [`crates/ai-memory-cli/src/commands/completions.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/completions.rs)

## Utility and Scripting Commands

| Command | Purpose | Source |
|---------|---------|--------|
| `run` | Execute single MCP tool call for scripting | [`run.rs`](https://github.com/akitaonrails/ai-memory/blob/main/run.rs) |

```bash

# Example: scripted tool invocation

ai-memory run memory_query --input '{"q": "test patterns"}'

```

## Summary

- **28+ subcommands** cover server operations, wiki CRUD, handoffs, maintenance, and agent integration
- **Each command** is implemented as a standalone Rust module in `crates/ai-memory-cli/src/commands/`
- **CLI parity with MCP**: commands expose the same tools agents use (`memory_query`, `memory_write_page`, etc.)
- **Critical maintenance**: `reindex` after bulk edits, `backup` before major changes, `data-purge` for cleanup
- **Workflow integration**: bootstrap → install-instructions → serve enables full agent memory in minutes

## Frequently Asked Questions

### How do I bootstrap ai-memory for an existing codebase?

Run `ai-memory bootstrap` after starting the server. This analyzes Git history, README files, and documentation to populate the wiki. Use `--dry-run` to preview imports without writing data.

### What's the difference between `install-instructions` and `install-skills`?

`install-instructions` installs both the routing snippet and Agent Skills (the default for new projects). `install-skills` installs only the skills—useful when your project already contains the routing snippet.

### When should I run `reindex`?

Execute `ai-memory reindex` after any bulk modification to markdown files in the wiki directory (external editors, git operations, or manual file changes). This rebuilds the SQLite FTS5 index used by `search`/`query`.

### How do handoffs work between sessions?

`handoff-begin` creates a transferable state container with a summary. The next session runs `handoff-accept` to consume it, receiving context about previous work. Use `handoff-cancel` to abort an unneeded handoff.