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

The .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. According to the implementation in 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 implementation reads these values to guarantee consistent MCP routing, while 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:

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

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:

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

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:

# 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 – Comprehensive specification covering format, sections, and resolution rules
• hooks/_lib.sh – Shell utility implementing the directory tree walk-up algorithm
• 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 – Logic ensuring marker files take precedence in project determination
• tests/hooks/test_lib.sh – Test suite validating marker file discovery and behavioral compliance

Summary

• The .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 and active_project.rs ensure markers determine routing and project precedence
• The complete specification is maintained in 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 file. This logic is implemented in hooks/_lib.sh for shell scripts and routing_snippet.rs for Rust components, ensuring consistent discovery across different client types.

What happens if no .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 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 within the akitaonrails/ai-memory repository, detailing the TOML schema, valid configuration values, and resolution precedence rules for the marker file system.

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