How the `.ai-memory.toml` File Supports Multi-Client Consultancies

The .ai-memory.toml marker file enables multi-client consultancies by declaring hierarchical workspace and project scopes that all AI agents, lifecycle hooks, and MCP (Machine-Client-Protocol) clients inherit through deterministic directory tree resolution.

Managing AI context across dozens of client repositories requires precise scoping mechanisms that persist across different tools and agents. The akitaonrails/ai-memory repository solves this through a declarative configuration file that establishes logical boundaries without hard-coding paths. By placing .ai-memory.toml in any ancestor directory, consultancies can define shared workspaces that isolate client data while allowing seamless collaboration across nested projects.

Hierarchical Walk-Up Resolution for Deterministic Scoping

The resolution algorithm walks up the directory tree from the current working directory until it locates the nearest .ai-memory.toml marker. As documented in docs/marker-file.md at line 34, this "nearest file wins" approach guarantees deterministic scope even when multiple repositories are nested or when consultants work across overlapping file systems. This mechanism ensures that agents always operate within the correct client boundary regardless of which subdirectory they execute from.

Explicit Workspace and Project Declaration

The marker file supports workspace = "NAME" and project = "NAME" fields that explicitly define scope boundaries. According to crates/ai-memory-mcp/src/server.rs at line 164, the server reads these exact names from the nearest marker when both are declared, forwarding them to static MCP clients to ensure every request is correctly namespaced without relying on directory inference. Additionally, crates/ai-memory-hooks/src/router.rs forwards marker-derived flags such as drop_subagent to lifecycle hooks, ensuring consistent policy enforcement across the toolchain.

Differentiating Static and Session-Aware MCP Clients

Session-aware clients automatically forward session IDs, allowing the server to resolve the current project from the marker on-the-fly. Static clients—those operating without a session bridge—must include both workspace and project in every call. As implemented in crates/ai-memory-core/src/routing_skills/ai-memory-retrieval/SKILL.md at line 26, the SDK reads the marker once and injects these values, eliminating the need for client code to derive scopes manually and preventing accidental cross-project data leakage.

Project Strategy Configuration for Repository Roots

By default, ai-memory derives project names from the current directory basename using basename resolution. For consultancies managing many sub-projects or microservices, the marker supports project_strategy = "repo-root", which forces all sub-folders to share the same project identifier. As noted in docs/design-decisions.md at line 244, this requires placing a marker in or above every repository to consolidate frontend/backend splits or service-oriented architectures under a single logical boundary.

Capture Filters and Briefing Automation

The marker file supports granular control over data capture and session initialization to meet privacy and regulatory requirements. The [capture] section accepts ignore_paths arrays to exclude sensitive patterns from recording, while the [briefing] section offers inject_on_session_start = true to automatically load project briefs into new sessions. Examples in tests/hooks/test_lib.sh at lines 52-53 and 205-206 demonstrate how consultancies can tailor data sharing across agents while respecting client confidentiality constraints.

Practical Implementation Examples

Configure a global consultancy workspace in your home directory to span multiple client repositories:

# ~/.ai-memory.toml – global workspace for a consultancy

workspace = "acme-consultancy"
project = "core-services"
project_strategy = "repo-root"

[capture]
ignore_paths = ["secrets/**", "tmp/**"]

[briefing]
inject_on_session_start = true

Execute commands from any subdirectory while maintaining correct scope:

# Example: running a command from any sub‑directory of the consultancy

cd ~/projects/acme/client-a/backend
ai-memory query "What authentication flow is used?"   # workspace & project auto‑injected

Implement a static Rust MCP client that reads the marker automatically:

// In a Rust MCP client (static mode)
let cfg = Config::load()?;                     // reads the nearest .ai-memory.toml
let client = AiMemoryClient::new(cfg.workspace, cfg.project);
client.run_query("list recent handoffs")?;

Override scope for a single session via CLI flags:

# Using the CLI to change the active project for a single session

ai-memory --workspace acme-consultancy --project api-admin session start

# All subsequent commands in this session use that project scope

Summary

• Hierarchical resolution guarantees deterministic scope across nested repositories by walking up to the nearest marker file.
• Explicit declarations in workspace and project fields namespaces every request without relying on directory names.
• Static client support eliminates cross-project leakage by injecting marker-derived values into clients that lack session bridges.
• Project strategy configuration consolidates microservice sub-projects under a single identifier using project_strategy = "repo-root".
• Capture and briefing controls enforce privacy boundaries through path exclusion patterns and automated context injection.

Frequently Asked Questions

How does .ai-memory.toml handle nested repositories with different scopes?

The system implements hierarchical walk-up resolution, traversing the directory tree until it finds the nearest marker file. As documented in docs/marker-file.md at line 34, the nearest configuration wins, ensuring that nested repositories maintain independent scopes while still inheriting parent workspace defaults when no local marker exists.

What is the difference between session-aware and static MCP clients in ai-memory?

Session-aware clients automatically forward session IDs, allowing the server to resolve projects dynamically from the marker file. Static clients must explicitly pass both workspace and project parameters with every call, requiring the SDK to read the nearest .ai-memory.toml once and inject those values, as specified in crates/ai-memory-core/src/routing_skills/ai-memory-retrieval/SKILL.md at line 26.

Can a consultancy use .ai-memory.toml to prevent sensitive files from entering shared memory?

Yes. The marker supports a [capture] section with ignore_paths arrays that exclude specific patterns from recording. As shown in tests/hooks/test_lib.sh at lines 52-53, consultancies can configure ignore_paths = ["secrets/**", "tmp/**"] to respect privacy constraints while maintaining shared project context for non-sensitive data.

How does the project_strategy setting support consultancies with many microservices?

Setting project_strategy = "repo-root" forces all subdirectories within a repository to share the same project identifier defined in the marker, rather than deriving names from individual folder basenames. According to docs/design-decisions.md at line 244, this ensures that microservices or frontend/backend splits within a single client engagement consolidate into one logical project scope rather than fragmenting across multiple identities.

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