What Happens When the Scope Is Missing During Read, Search, or Embed Operations in ai-memory

When the scope is missing during read, search, or embed operations in ai-memory, the system immediately returns a StoreError::MissingScope error after the resolver fails to locate the workspace-project tuple in the SQLite scopes table, preventing any database access.

The ai-memory repository provides a scoped storage layer for AI applications, where every data access operation is bound to a specific workspace and project context. Understanding how the system handles missing scope references is critical for implementing proper error handling in production deployments.

Scope Resolution Mechanism in ai-memory

Before executing any read, search, or embed operation, ai-memory validates the scope through the scope resolver implemented in crates/ai-memory-core/src/workspace.rs.

The resolver queries the SQLite scopes table using the resolve_existing_scope function to verify that the requested workspace and project combination exists. If the tuple is not found, the function returns the error variant ScopeError::Missing immediately.

Error Propagation Through the System Stack

Once the core resolver detects a missing scope, the error propagates through distinct layers with specific transformations at each boundary.

Store Layer Translation

The public store API in crates/ai-memory-store/src/lib.rs translates the core ScopeError::Missing into StoreError::MissingScope. This conversion occurs in the implementation of read_page, search_page, and embed_page methods before any database access occurs, ensuring the error surfaces at the API boundary with a consistent type.

MCP HTTP Response Mapping

The MCP route handlers in crates/ai-memory-mcp/src/routes.rs map StoreError::MissingScope to an HTTP 404 Not Found response. The client receives a JSON body formatted as {"error":"scope not found"} to indicate the specific resource context that could not be located.

Operation-Specific Failure Behavior

All three primary operations—read, search, and embed—follow identical failure paths when encountering missing scopes, aborting before touching any data indexes.

Read Operations with read_page

When calling read_page with an invalid scope, the operation aborts before querying the page content store. The function returns Err(StoreError::MissingScope) immediately after the resolver check fails, preventing any filesystem or database access for content retrieval.

Search Operations with search_page

The full-text search implementation performs scope resolution prior to accessing the FTS indexes. A missing scope prevents the search query from executing, returning the same error variant without touching the search index or performing any tokenization operations.

Embed Operations with embed_page

Vector embedding requests also validate scope existence before accessing the vector store. The embed_page function fails fast with MissingScope rather than attempting to generate embeddings or query the vector index for non-existent contexts.

Handling Missing Scope Errors in Application Code

Applications integrating ai-memory should explicitly handle StoreError::MissingScope to provide graceful degradation and user-friendly error messages.

// Reading a page with explicit scope error handling
use ai_memory_store::{Client, StoreError};

let client = Client::new(...);
match client.read_page(workspace_id, project_id, "some/page.md") {
    Ok(content) => println!("Page: {}", content),
    Err(StoreError::MissingScope) => eprintln!("Error: scope does not exist"),
    Err(e) => eprintln!("Other error: {}", e),
}

// Performing a full-text search with missing scope protection
match client.search(
    workspace_id,
    project_id,
    "keyword",
    /* pagination parameters */
) {
    Ok(results) => println!("Found {} hits", results.len()),
    Err(StoreError::MissingScope) => eprintln!("Cannot search – scope missing"),
    Err(e) => eprintln!("Search error: {}", e),
}

// Requesting embeddings with scope validation
match client.embed(
    workspace_id,
    project_id,
    "The quick brown fox…",
) {
    Ok(vec) => println!("Embedding size: {}", vec.len()),
    Err(StoreError::MissingScope) => eprintln!("Embedding failed – missing scope"),
    Err(e) => eprintln!("Embedding error: {}", e),
}

Summary

• Validation occurs first: Every read, search, and embed operation validates scope existence via resolve_existing_scope in crates/ai-memory-core/src/workspace.rs before accessing data stores or indexes.
• Immediate failure: Missing scopes trigger ScopeError::Missing at the core level, which propagates as StoreError::MissingScope through the store layer without retry or fallback logic.
• No automatic creation: The system does not create default scopes or proceed with unscoped queries; it fails fast to prevent data leakage and ensure strict isolation.
• HTTP 404 mapping: MCP endpoints translate missing scope errors into standard HTTP 404 responses with descriptive JSON payloads for REST clients.
• Consistent across operations: Read, search, and embed operations share identical scope validation logic and error handling paths, ensuring predictable behavior regardless of operation type.

Frequently Asked Questions

What error type does ai-memory return when the scope is missing?

The system returns StoreError::MissingScope at the store API level. This originates from ScopeError::Missing in the core workspace resolver and propagates through the stack without modification until the presentation layer maps it to an HTTP 404 response.

Does ai-memory create a default scope automatically if one is missing?

No. The system implements fail-fast behavior. If the (workspace, project) tuple does not exist in the SQLite scopes table, the operation aborts immediately with an error rather than creating a fallback scope, proceeding with unscoped access, or attempting automatic scope creation.

Which HTTP status code does the MCP server return for missing scope errors?

The MCP route handlers in crates/ai-memory-mcp/src/routes.rs map StoreError::MissingScope to HTTP 404 Not Found. The response includes a JSON payload with the message "scope not found" to indicate the specific failure reason to API consumers.

Can read, search, and embed operations proceed without a valid scope?

No. All three operations require valid scope resolution before executing. The read_page, search_page, and embed_page functions in crates/ai-memory-store/src/lib.rs each perform scope validation as their first operation, ensuring no database queries execute against content stores, FTS indexes, or vector indexes when the scope is absent.

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