# How to Query the Compiled ai-memory Wiki for Specific Information

> Learn how to query the compiled ai-memory wiki using HTTP GET, the CLI, or the Rust API. Leverage FTS5 full-text search in SQLite for efficient information retrieval.

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

---

**You can query the compiled ai-memory wiki using three interfaces: an HTTP GET `/search` endpoint, the `ai-memory search` CLI command, or the `ReaderPool::search_pages` Rust API, all of which leverage an FTS5 full-text index stored in SQLite.**

The ai-memory system by akitaonrails maintains a Git-backed wiki tree that compiles markdown pages into a searchable SQLite store. When you need to query the compiled ai-memory wiki for specific information, the system provides multiple access patterns that all read from the same FTS5 index, ensuring consistent results across HTTP, command-line, and programmatic interfaces.

## Three Methods to Query the ai-memory Wiki

The system exposes search functionality through three entry points that share the same underlying implementation in [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs).

### HTTP GET /search Endpoint

The web server exposes a REST endpoint that accepts search queries via URL parameters. In [`crates/ai-memory-web/src/routes/search.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-web/src/routes/search.rs), the route handler parses `q` (required), `workspace`, `project`, and `limit` parameters, then delegates to `ReaderPool::search_pages` for global searches or `search_pages_for_project` for scoped searches.

```bash

# Global search across all workspaces

curl "http://localhost:49374/search?q=tokenization&limit=5"

# Scoped search within specific workspace and project

curl "http://localhost:49374/search?q=tokenization&workspace=default&project=my-project&limit=5"

```

The endpoint returns a JSON array of `SearchHit` objects containing `page_id`, `title`, `snippet`, `workspace`, `project`, and `path`.

### CLI ai-memory search Command

The command-line interface provides the `search` subcommand 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). This command opens the SQLite store, initializes a `ReaderPool`, and forwards queries to the same reader methods used by the HTTP API.

```bash

# Global search with result limiting

ai-memory search "tokenization" --limit 5

# Scoped search with workspace and project filters

ai-memory search "tokenization" --workspace default --project my-project --limit 5

```

Results display as a formatted table showing page identifiers, titles, and file paths.

### Rust ReaderPool API

Library users can interact directly with the search index through the `ReaderPool` struct defined in [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs). The API offers two primary methods:

- **`search_pages(term, limit)`**: Performs a global search across all workspaces and projects.
- **`search_pages_for_project(ws, proj, term, limit, None)`**: Restricts results to a specific workspace and project combination.

```rust
use ai_memory_store::ReaderPool;
use ai_memory_core::ids::WorkspaceId;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let reader: ReaderPool = /* initialize reader */;
    
    // Global search
    let hits = reader.search_pages("tokenization".into(), 5).await?;
    
    // Scoped search
    let ws = WorkspaceId::parse("default")?;
    let proj = "my-project".into();
    let scoped = reader
        .search_pages_for_project(ws, proj, "tokenization".into(), 5, None)
        .await?;
        
    for hit in scoped {
        println!("{} – {} ({})", hit.title, hit.path, hit.workspace);
    }
    Ok(())
}

```

## How the FTS5 Search Index Works

The search capability relies on SQLite's FTS5 (Full-Text Search) extension. When you query the compiled ai-memory wiki, you are querying the `pages_fts` virtual table defined in [`crates/ai-memory-store/src/schema.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/schema.rs).

The indexing workflow operates as follows:

1. **Wiki writes**: When `Wiki::write_page` is called in [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs), it writes markdown to disk atomically and sends an `UpsertPage` command to the single-writer SQLite actor.
2. **Index updates**: The writer updates the `pages_fts` virtual table within the same transaction, ensuring the search index remains synchronized with the wiki content.
3. **Query execution**: `ReaderPool` executes FTS5 `MATCH ?` queries against the index, then enriches results with metadata including workspace, project, and file path information.

## Core Source Files and Implementation Details

Understanding these key files helps when extending or debugging search functionality:

| Component | Source File | Purpose |
|-----------|-------------|---------|
| **Wiki Core** | [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs) | Handles atomic markdown writes and triggers FTS5 index updates via `Wiki::write_page`. |
| **Store Reader** | [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs) | Implements `search_pages` and `search_pages_for_project` methods that execute FTS5 queries. |
| **Web Routes** | [`crates/ai-memory-web/src/routes/search.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-web/src/routes/search.rs) | Defines the HTTP GET `/search` endpoint and parameter parsing logic. |
| **CLI Command** | [`crates/ai-memory-cli/src/commands/search.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/search.rs) | Implements the `ai-memory search` subcommand interface. |
| **Database Schema** | [`crates/ai-memory-store/src/schema.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/schema.rs) | Defines the `pages_fts` virtual table structure using FTS5. |

## Summary

- **HTTP API**: Query via `GET /search?q=term&workspace=...&project=...` in [`crates/ai-memory-web/src/routes/search.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-web/src/routes/search.rs) for JSON results.
- **CLI Tool**: Use `ai-memory search "term" --workspace ... --project ...` defined 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).
- **Rust Library**: Call `ReaderPool::search_pages()` or `search_pages_for_project()` from [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs) for programmatic access.
- **Storage**: All methods query the same FTS5 index in SQLite (`pages_fts` table), ensuring consistency across interfaces.
- **Indexing**: The index updates automatically when `Wiki::write_page` modifies content in [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs).

## Frequently Asked Questions

### What query syntax does the ai-memory wiki search support?

The search uses SQLite FTS5's `MATCH` syntax. In [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs), queries are passed directly to the FTS5 virtual table using parameterized `MATCH ?` statements. This supports standard FTS5 boolean operations (AND, OR, NOT) and phrase queries, though the exact syntax depends on how the `pages_fts` table is configured in [`crates/ai-memory-store/src/schema.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/schema.rs).

### Can I search across multiple workspaces simultaneously?

Yes. When you call `ReaderPool::search_pages()` without workspace or project parameters (or use the HTTP endpoint without `workspace`/`project` filters), the query executes against the global FTS5 index. This searches across all workspaces and projects stored in the SQLite database. Scoped searches via `search_pages_for_project` restrict results to specific workspace-project combinations.

### How does the search index stay synchronized with wiki changes?

The `Wiki::write_page` method in [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs) handles synchronization. It performs atomic markdown file writes and sends an `UpsertPage` command to the SQLite writer actor. The writer updates the `pages_fts` virtual table within the same transaction, ensuring the FTS5 index reflects the current wiki state immediately after each write operation.

### What fields are included in search results?

Search results return `SearchHit` structs containing: `page_id` (unique identifier), `title` (page heading), `snippet` (context around the match), `workspace` (workspace identifier), `project` (project name), and `path` (relative file path). These fields are populated in [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs) after executing the FTS5 query.