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

> Discover how the .ai-memory.toml file empowers multi-client consultancies by defining workspace and project scopes for AI agents and clients. Learn about deterministic directory tree resolution.

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

---

**The [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.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`](https://github.com/akitaonrails/ai-memory/blob/main/.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`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) marker. As documented in [`docs/marker-file.md`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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:

```toml

# ~/.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:

```bash

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

```rust
// 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:

```bash

# 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`](https://github.com/akitaonrails/ai-memory/blob/main/.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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) once and inject those values, as specified in [`crates/ai-memory-core/src/routing_skills/ai-memory-retrieval/SKILL.md`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/routing_skills/ai-memory-retrieval/SKILL.md) at line 26.

### Can a consultancy use [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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.