# What Is the Purpose of the `.ai-memory.toml` Marker File?

> Understand the purpose of the .ai-memory.toml marker file. Learn how it defines your project's logical workspace and enables the ai-memory system to discover your repository.

- 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) file serves as a project-wide marker that enables the ai-memory system to discover the logical workspace and project a repository belongs to by walking up the directory tree and parsing the nearest configuration file.**

The `akitaonrails/ai-memory` repository uses this marker file as the single source of truth for scope resolution, routing, and behavior configuration. When lifecycle hooks or MCP clients execute, they rely on this file to determine the exact workspace and project identifiers for all subsequent operations.

## How the Marker File Drives Scope Resolution

The discovery mechanism begins at the current working directory and walks upward until it locates the nearest [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml). According to the implementation in [`hooks/_lib.sh`](https://github.com/akitaonrails/ai-memory/blob/main/hooks/_lib.sh), this shell utility provides the core walk-up logic that hooks use to anchor themselves to the correct project context.

Once discovered, the file contents pin the **workspace** and **project** identifiers. The [`crates/ai-memory-core/src/routing_snippet.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/routing_snippet.rs) implementation reads these values to guarantee consistent MCP routing, while [`crates/ai-memory-core/src/active_project.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/active_project.rs) contains logic ensuring the marker file always wins when determining the active project, overriding any environmental defaults.

## Configuration Fields and Sections

### Workspace and Project Identification

The root-level `workspace` and `project` fields declare the identifiers that scope all reads, writes, and queries:

```toml
workspace = "my-company"
project = "awesome-app"

```

These values serve as the exact routing keys that MCP clients extract when calling resolution functions.

### Project Resolution Strategy

The optional `project_strategy` field controls how the project name is derived. Setting `project_strategy = "repo-root"` forces the system to use the repository root directory name rather than the current subdirectory, which prevents the creation of phantom projects when working in nested folders. This behavior is documented in [`docs/design-decisions.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/design-decisions.md) under the install-time project strategy section.

### Capture and Briefing Controls

The marker file configures hook behavior through dedicated sections:

- **`[capture]`**: Contains filtering rules such as `ignore_paths = ["secret/**"]` to exclude sensitive files from event processing
- **`[briefing]`**: Controls metadata injection with options like `inject_on_session_start = true` to automatically prepend context at the beginning of sessions

## Practical Implementation Examples

### Creating a Marker File

Initialize the configuration at your repository root:

```bash
cat > .ai-memory.toml <<EOF
workspace = "my-company"
project = "awesome-app"
project_strategy = "repo-root"

[capture]
ignore_paths = ["secret/**"]

[briefing]
inject_on_session_start = true
EOF

```

### Hook Integration

Lifecycle hooks utilize the marker through the shared library implemented in [`hooks/_lib.sh`](https://github.com/akitaonrails/ai-memory/blob/main/hooks/_lib.sh):

```bash
./hooks/claude-code/session-start.sh

```

The hook script transparently walks up the directory tree to locate the marker and forwards the parsed settings to the ai-memory core.

### Programmatic Scope Resolution

Rust-based MCP clients resolve scope programmatically using the core routing functions:

```rust
use ai_memory_core::routing::resolve_scope;
use std::path::Path;

// Resolve the current scope based on the nearest .ai-memory.toml
let scope = resolve_scope(Path::new(".")).await?;
assert_eq!(scope.workspace, "my-company");
assert_eq!(scope.project, "awesome-app");

```

### Overriding Default Naming

Without an explicit marker, the system defaults to using the current directory name as the project identifier. The `project_strategy` field overrides this behavior:

```toml

# Forces project name to match repository root rather than subdirectory

project_strategy = "repo-root"

```

## Key Source Files

The marker file system spans multiple components across the codebase:

- **[`docs/marker-file.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md)** – Comprehensive specification covering format, sections, and resolution rules
- **[`hooks/_lib.sh`](https://github.com/akitaonrails/ai-memory/blob/main/hooks/_lib.sh)** – Shell utility implementing the directory tree walk-up algorithm
- **[`crates/ai-memory-core/src/routing_snippet.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/routing_snippet.rs)** – Routing code that extracts workspace and project names from markers for MCP clients
- **[`crates/ai-memory-core/src/active_project.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/active_project.rs)** – Logic ensuring marker files take precedence in project determination
- **[`tests/hooks/test_lib.sh`](https://github.com/akitaonrails/ai-memory/blob/main/tests/hooks/test_lib.sh)** – Test suite validating marker file discovery and behavioral compliance

## Summary

- The [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) file acts as the **single source of truth** for workspace and project identification in the ai-memory ecosystem
- The system employs an **upward directory walk** mechanism starting from the current working directory to locate the nearest marker
- Configuration options include **workspace/project identifiers**, **resolution strategies** to avoid phantom projects, and **capture/briefing** behavioral controls
- Core implementations in [`routing_snippet.rs`](https://github.com/akitaonrails/ai-memory/blob/main/routing_snippet.rs) and [`active_project.rs`](https://github.com/akitaonrails/ai-memory/blob/main/active_project.rs) ensure markers determine routing and project precedence
- The complete specification is maintained in [`docs/marker-file.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md)

## Frequently Asked Questions

### How does ai-memory locate the nearest marker file?

When a hook or MCP client initializes, it executes a directory traversal starting from the current working directory and moving upward through parent directories until it encounters an [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) file. This logic is implemented in [`hooks/_lib.sh`](https://github.com/akitaonrails/ai-memory/blob/main/hooks/_lib.sh) for shell scripts and [`routing_snippet.rs`](https://github.com/akitaonrails/ai-memory/blob/main/routing_snippet.rs) for Rust components, ensuring consistent discovery across different client types.

### What happens if no [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) file exists?

Without a marker file present, the system falls back to default behaviors, typically using the current directory name as the project identifier. However, this can lead to fragmented project contexts or phantom projects when working within subdirectories of a larger repository, which is why explicit marker files are recommended for production use.

### Can I use different project names for subdirectories in the same repository?

Yes, by omitting `project_strategy = "repo-root"` or placing separate [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) files in specific subdirectories, you can scope different parts of a monorepo to distinct project identifiers. The nearest marker always takes precedence, allowing granular control over how ai-memory segments your codebase.

### Where is the marker file specification documented?

The authoritative specification resides in [`docs/marker-file.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md) within the `akitaonrails/ai-memory` repository, detailing the TOML schema, valid configuration values, and resolution precedence rules for the marker file system.