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

> Master the ai-memory CLI with our complete guide to `memory_query`. Run ad-hoc natural-language queries against your vector store effortlessly.

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

---

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

```bash

# Start the server if not already running

ai-memory start

```

## `memory_query` Command Syntax

The basic structure follows this pattern:

```bash
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

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

```

### Limited Results with JSON Output

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

```

### Query Specific Project in Workspace

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

```

### Debug with Verbose Similarity Scores

```bash
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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-llm/src/embedder.rs)
3. **Vector search** with RRF ranking in [`crates/ai-memory-store/src/query.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/query.rs)
4. **HTTP transport** to [`crates/ai-memory-mcp/src/routes/query.rs`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/memoryquery.rs) — CLI argument parsing and request construction
- [`crates/ai-memory-store/src/query.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/query.rs) — Core embedding, vector-RRF search, and result assembly
- [`crates/ai-memory-mcp/src/routes/query.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/routes/query.rs) — HTTP endpoint for server-mediated queries
- [`crates/ai-memory-llm/src/embedder.rs`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/query.rs).