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

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:

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

Implementation resides in crates/ai-memory-cli/src/commands/serve.rs. This handles HTTP/MCP transport initialization and the web interface.

Verify server health with status:

ai-memory status

This prints bind address, data directory, and connected projects—implemented in 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
data-purge	Removes temporary files and stale caches	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
purge-project	Deletes entire project including wiki and observations	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:

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

Install Routing and Skills

Four related commands configure agent integration:

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

# 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
Read	read-page	crates/ai-memory-cli/src/commands/read_page.rs
Delete	delete-page	crates/ai-memory-cli/src/commands/delete_page.rs

Example workflow:

# 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:

ai-memory search "cargo fmt" --explain

For vector-based semantic search, explicitly trigger embedding:

ai-memory embed

Source for search: crates/ai-memory-cli/src/commands/search.rs
Source for embed: 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
Consume	handoff-accept	memory_handoff_accept	handoff_accept.rs
Abort	handoff-cancel	memory_handoff_cancel	handoff_cancel.rs

# 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): Reattaches a session and its observations to a different project
• move-project (move_project.rs): Renames or relocates a project while preserving all content

Auto-Improvement and Curation

Automated Quality Pipelines

# 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: Triggers LLM-based review of completed sessions
• auto_improve_report.rs: Formats suggestions for human review

Manual Curation

• curator (curator.rs): Manually runs consolidation on selected pages
• checkpoints (checkpoints.rs): Lists or manipulates session checkpoints from LLM-driven consolidation

Backup, Restore, and Portability

Data Protection

# 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: Dumps wiki + SQLite to tarball
• restore.rs: Overwrites current data with backup contents

Authentication and Shell Integration

Provider Credentials

Manage LLM provider authentication:

ai-memory auth login openai
ai-memory auth status

Implementation: crates/ai-memory-cli/src/commands/auth.rs

Shell Completions

Generate tab-completion scripts for your shell:

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

Utility and Scripting Commands

Command	Purpose	Source
run	Execute single MCP tool call for scripting	run.rs

# 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.

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