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

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.

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

# 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. This command opens the SQLite store, initializes a ReaderPool, and forwards queries to the same reader methods used by the HTTP API.

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

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.

The indexing workflow operates as follows:

1. Wiki writes: When Wiki::write_page is called in 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	Handles atomic markdown writes and triggers FTS5 index updates via Wiki::write_page.
Store Reader	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	Defines the HTTP GET /search endpoint and parameter parsing logic.
CLI Command	crates/ai-memory-cli/src/commands/search.rs	Implements the ai-memory search subcommand interface.
Database Schema	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 for JSON results.
• CLI Tool: Use ai-memory search "term" --workspace ... --project ... defined in 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 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.

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

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 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 after executing the FTS5 query.

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