How Capture Exclusions Work in ai‑memory Using `.ai‑memory.toml`

To exclude files from being captured by ai‑memory, add a [capture] section with ignore_paths to your .ai‑memory.toml marker file; paths matching these glob patterns are dropped before reaching the capture pipeline.

The akitaonrails/ai‑memory project records hook payloads and file operations to provide context for LLM agents. By default, this capture pipeline is all‑inclusive, but you can define capture exclusions via configuration to ensure sensitive or build‑artifact paths never persist in the memory store.

Understanding the [capture] Configuration Section

The [capture] table in .ai‑memory.toml recognizes a single key: ignore_paths. This array accepts glob patterns that determine which relative paths are filtered out.

The ignore_paths Array

When specified, ignore_paths contains strings such as secret/** or **/*.key. According to the marker file documentation in [docs/marker-file.md](https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md#L161-L171), these patterns define the exclusion list. If the array is empty or the section is omitted, ai‑memory defaults to capturing every eligible path.

How Pattern Matching Works

The exclusion engine adheres to .gitignore semantics with strict resource limits:

• ** matches zero or more directory components.
• Case sensitivity follows the host OS rules (case‑insensitive on Windows, case‑sensitive on POSIX).
• Each pattern entry is limited to 32 KB, and the total list must not exceed 64 KB. Violating these limits causes the entire marker file to be ignored.

Enforcement Points in the Codebase

Capture exclusions are enforced at multiple architectural layers to guarantee that excluded data is never spooled or transmitted.

Policy Resolution in capture_policy.rs

The core decision logic lives in [crates/ai-memory-hooks/src/capture_policy.rs](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-hooks/src/capture_policy.rs#L7-L28). The CapturePolicy::resolve function compiles the ignore_paths patterns into an internal matcher. When a payload arrives, policy.inspect() compares the file path against these patterns; a match returns PolicyState::Drop, immediately terminating the capture flow.

Hook Command Integration

When executing native hook commands, the CLI loads the nearest .ai‑memory.toml by walking upward from the current working directory. The parsing logic in [crates/ai-memory-cli/src/commands/hook_capture.rs](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/hook_capture.rs#L60-L73) extracts the [capture] section and builds the configuration before any data reaches the provider API.

Practical Configuration Examples

Basic Exclusion Patterns

Place the following .ai‑memory.toml at your repository root to exclude sensitive directories and key files:

[capture]

# Exclude everything under secret/ and any .key files anywhere

ignore_paths = ["secret/**", "**/*.key"]

Verifying Exclusions via CLI

You can inspect the effective policy without triggering a capture:

# Renders the active ignore_paths for the current directory

ai-memory render capture-policy

Programmatic Policy Check

The following Rust snippet demonstrates how the policy evaluates a file operation payload:

use ai_memory_hooks::capture_policy::{CapturePolicy, PolicyState};
use ai_memory_types::AgentKind;

// Resolve policy from the nearest marker file
let policy = CapturePolicy::resolve(&config, repo_root, None);

// Simulate a file edit payload
let payload = json!({
    "tool_name": "Edit",
    "tool_input": { "path": "secret/config.json" }
});

let decision = policy.inspect(AgentKind::Codex, &payload, repo_root);

// Verification: matched paths return Drop
assert_eq!(decision.protocol().policy_state(), PolicyState::Drop);

Summary

• Capture exclusions are defined in the [capture] section of .ai‑memory.toml using the ignore_paths key.
• Patterns follow .gitignore glob semantics with hard limits of 32 KB per entry and 64 KB total.
• The CapturePolicy::resolve function in capture_policy.rs evaluates paths and returns PolicyState::Drop for matches.
• Exclusions apply to all native hook commands and file‑operation payloads before spooling or remote transmission.
• Scope is determined by the nearest marker file found by walking up from the working directory.

Frequently Asked Questions

What happens if I don't specify ignore_paths?

If the [capture] section is missing or ignore_paths is empty, ai‑memory captures every eligible file operation and hook payload. No filtering occurs, and all data enters the memory store.

Do capture exclusions affect all ai‑memory commands?

Yes. The policy is applied uniformly across native ai‑memory hook commands, automatic tool calls that manipulate files, and any tool_name/tool_input payloads processed by the capture pipeline. The exclusion check occurs before data is spooled or sent to an LLM provider.

Can I use negative patterns or exceptions in ignore_paths?

The current implementation treats every entry as a pure exclusion pattern. Negation patterns (e.g., !important.key) are not supported in capture_policy.rs. You must explicitly enumerate the paths to exclude.

Where should I place the .ai-memory.toml file for best results?

Place the file at the repository root to establish a global policy. ai‑memory searches upward from the current working directory and stops at the first marker found, allowing subdirectory‑specific overrides if needed.

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