How to Use the `memory_query` Tool in ai-memory: Complete CLI Guide

The memory_query tool is a sub-command of the ai-memory CLI that runs ad-hoc natural-language queries against the vector-augmented memory store without requiring a full program.

The memory_query command provides direct access to ai-memory's semantic search capabilities from the terminal. It embeds your query text using the configured Embedder provider, matches it against stored embeddings, and returns ranked results from the memory store.

Prerequisites and Setup

Before using memory_query, ensure the ai-memory server is running or a local SQLite store is accessible. The CLI communicates with the server over the MCP HTTP interface at the /api/v1/query endpoint.

# Start the server if not already running

ai-memory start

memory_query Command Syntax

The basic structure follows this pattern:

ai-memory memoryquery --query "<natural language query>" [OPTIONS]

Available Options

Option	Description
--query <TEXT>	Required. The natural-language query string to embed and search
--limit <N>	Maximum results to return (default: 10)
--project <NAME>	Restrict search to a specific project
--scope <WORKSPACE>/<PROJECT>	Explicit workspace/project scope for multi-tenant setups
--json	Output results as JSON for programmatic processing
--verbose	Display embedding dimensions and similarity scores

Practical Code Examples

Basic Query Against Default Project

ai-memory memoryquery --query "how to add a new Rust crate"

Limited Results with JSON Output

ai-memory memoryquery \
  --query "authentication token handling" \
  --limit 5 \
  --json

Query Specific Project in Workspace

ai-memory memoryquery \
  --query "how does the embedder trait work?" \
  --scope my_workspace/my_project

Debug with Verbose Similarity Scores

ai-memory memoryquery \
  --query "vector search" \
  --verbose

Internal Implementation

The memory_query tool delegates all heavy lifting to the ai-memory-store crate, ensuring consistent behavior with the rest of the system.

Query Execution Flow

1. CLI parsing in crates/ai-memory-cli/src/commands/memoryquery.rs — extracts arguments and builds the request
2. Embedding generation via the configured Embedder trait in crates/ai-memory-llm/src/embedder.rs
3. Vector search with RRF ranking in crates/ai-memory-store/src/query.rs
4. HTTP transport to crates/ai-memory-mcp/src/routes/query.rs when server-mediated
5. Result formatting with title, path, author, and highlighted snippets

Key Source Files

• crates/ai-memory-cli/src/commands/memoryquery.rs — CLI argument parsing and request construction
• crates/ai-memory-store/src/query.rs — Core embedding, vector-RRF search, and result assembly
• crates/ai-memory-mcp/src/routes/query.rs — HTTP endpoint for server-mediated queries
• crates/ai-memory-llm/src/embedder.rs — Embedder trait definition and provider implementations

These components maintain system invariants: single-writer SQLite actor concurrency, typed scope IDs, and consistent vector ranking algorithms.

Scope and Project Selection

Without explicit flags, memory_query uses the active project from the current session. For multi-tenant deployments:

• --project filters within the default workspace
• --scope specifies full workspace_id/project_id identifiers

This scoping ensures queries respect data isolation boundaries defined in the ai-memory architecture.

Output Formats

Human-Readable (Default)

Results display with:

• Document title
• File path
• Author attribution
• Snippet with query term highlighting

JSON (--json)

Structured output suitable for piping to other tools or scripts. Includes full metadata and similarity scores.

Verbose (--verbose)

Adds diagnostic information:

• Embedding dimension
• Raw similarity scores
• Query processing timing

Summary

• memory_query enables ad-hoc semantic search from the command line without writing code
• Queries are embedded and matched using the same pipeline as programmatic API access
• Scope isolation through --project and --scope supports multi-workspace deployments
• JSON output integrates with shell scripts and CI pipelines
• Implementation spans CLI, store, MCP, and LLM crates for modular, maintainable design

Frequently Asked Questions

Does memory_query require the ai-memory server to be running?

The CLI prefers server mode via MCP HTTP but can fall back to direct SQLite access for local stores. Server mode provides better concurrency control and supports remote deployments.

Which embedding provider does memory_query use?

The command uses whichever Embedder provider is configured in your ai-memory setup—OpenAI, Anthropic, or local models—defined in crates/ai-memory-llm/src/embedder.rs.

How does memory_query handle multi-project deployments?

The --scope parameter accepts workspace_id/project_id format, matching the typed scope identifier system used throughout ai-memory for strict data isolation.

What similarity algorithm powers the search?

Results are ranked using vector-RRF (Reciprocal Rank Fusion), combining vector similarity with optional keyword signals in crates/ai-memory-store/src/query.rs.

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