How to Configure the Auto-Scope Resolver for Dynamic Workspace/Project Routing in ai-memory

Configure ai-memory's auto-scope resolver by using CLI flags (--workspace and --project), setting the AI_MEMORY_AUTO_SCOPE environment variable, or creating a .ai-memory.toml marker file in your project root.

The akitaonrails/ai-memory repository implements a dynamic routing system that automatically determines which workspace and project context to use for each request. Understanding how to configure the auto-scope resolver for dynamic workspace/project routing ensures your AI memory contexts remain organized and isolated across different projects.

Understanding the Resolution Order

The auto-scope resolver evaluates configuration sources in strict priority order. When you execute any ai-memory command, the resolver checks for explicit CLI flags first, then environment variables, and finally marker files. If none are found, it falls back to default values defined in ScopeResolver::lookup_existing within crates/ai-memory-store/src/scope.rs.

Configuration Methods

CLI Flags (Highest Priority)

The most direct method involves passing explicit identifiers to any ai-memory sub-command. According to the source implementation in the CLI layer, the --workspace and --project flags override all other configuration sources.

ai-memory --workspace my_ws --project my_proj embed \
    --model gpt-4o-mini "Hello world"

Environment Variables

For shell-session persistence, set the AI_MEMORY_AUTO_SCOPE environment variable. The parser in crates/ai-memory-cli/src/config.rs reads this variable, which accepts a comma-separated list of key-value pairs. The legacy AI_MEMORY_AUTO_PROJECT variable is also supported for backward compatibility.

export AI_MEMORY_AUTO_SCOPE="workspace=my_ws,project=my_proj"
ai-memory bootstrap   # the resolver will use the IDs above

Marker Files (.ai-memory.toml)

Place a hidden .ai-memory.toml file in your project directory to bind that directory tree to specific workspace and project IDs. The resolver walks up the directory tree until it finds this marker, implementing the discovery logic in the scope resolution module.

# .ai-memory.toml placed in the project root

workspace = "my_ws"
project   = "my_proj"

Any command executed from this directory or its descendants automatically uses these configured IDs.

Implementation Details

The core resolution logic resides in crates/ai-memory-store/src/scope.rs, which defines the ScopeResolver struct. Key methods include resolve_many_existing for batch operations and lookup_existing for retrieving specific scope contexts.

In crates/ai-memory-mcp/src/server.rs, HTTP handlers access the resolver through the scope_resolver() method, which returns a fresh instance bound to the current request's reader pool. This dynamic instantiation occurs via ScopeResolver::new(&reader, ws, proj) for every request, ensuring complete isolation between concurrent operations.

Fallback Behavior

When no configuration sources are present, the resolver defaults to the default workspace (default) and the current project (the most recently used project for that workspace). This fallback mechanism ensures the system remains functional even without explicit configuration, as implemented in the lookup_existing method.

Programmatic Usage

For Rust developers integrating ai-memory directly, instantiate the resolver explicitly with your desired identifiers to bypass automatic detection:

use ai_memory_store::{ScopeResolver, ReaderPool};

fn do_something(reader: &ReaderPool) {
    // Resolve using explicit IDs (overrides env/marker)
    let resolver = ScopeResolver::new(reader, "my_ws", "my_proj");
    let page = resolver.lookup_existing("my_page").unwrap();
    // … use `page` …
}

This approach gives you full control over scope resolution by directly invoking the constructor defined in crates/ai-memory-store/src/scope.rs.

Summary

• The auto-scope resolver evaluates CLI flags, then environment variables, then marker files to determine workspace and project routing.
• Core implementation files include crates/ai-memory-store/src/scope.rs for resolution logic and crates/ai-memory-cli/src/config.rs for environment parsing.
• Fallback defaults apply when no sources are found, using the default workspace and most recent project.
• The resolver is instantiated dynamically for each request via ScopeResolver::new().

Frequently Asked Questions

What is the priority order for auto-scope configuration sources?

The resolver checks sources in strict sequence: first explicit CLI flags (--workspace, --project), then the AI_MEMORY_AUTO_SCOPE environment variable, then .ai-memory.toml marker files in the directory hierarchy. If none exist, it falls back to default workspace and current project values defined in the scope resolver implementation.

Can I use multiple configuration methods at once?

Yes, but only the highest-priority source takes effect. For example, if you specify --workspace on the command line, it overrides any environment variable or marker file settings for that execution. The environment variable overrides marker files but is overridden by CLI flags.

Where is the auto-scope resolver implemented in the source code?

The core logic lives in crates/ai-memory-store/src/scope.rs within the ScopeResolver struct. The CLI integration parsing AI_MEMORY_AUTO_SCOPE is in crates/ai-memory-cli/src/config.rs, while the MCP server exposes it through scope_resolver() in crates/ai-memory-mcp/src/server.rs.

What happens if no workspace or project is configured?

The system defaults to the workspace named default and selects the most recently used project for that workspace. This fallback behavior is handled by the lookup_existing method in crates/ai-memory-store/src/scope.rs.

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