Capture Exclusion Policy in ai-memory: How It Filters File-Tool Events

The capture exclusion policy is a per-repository configuration that tells ai-memory which file-tool events should not be recorded as observations by matching their paths against glob patterns in the repository's marker file.

The capture exclusion policy is a core feature of the akitaonrails/ai-memory open-source project that prevents noisy or sensitive files from entering the observation pipeline. Defined in each repository's docs/marker-file.md, it gives project owners fine-grained control over what gets captured without affecting unrelated projects.

What Is the Capture Exclusion Policy?

The capture exclusion policy is a declarative filter declared in the [capture] section of a repository's marker file (docs/marker-file.md). It consists of an ignore_paths array that lists glob patterns for paths that must be excluded from recording.

When active, the policy applies before any deeper data analysis occurs. It performs a lexical match on the file-tool event's path string to decide whether the event should proceed into the capture pipeline.

How the Policy Filters File-Tool Events

Declaring Exclusions in the Marker File

A repository configures the policy by adding a TOML [capture] table with an ignore_paths array. Each entry is a glob pattern that targets files or directories to skip.

# docs/marker-file.md – example capture exclusion

[capture]
ignore_paths = [
  "**/target/**",      # compiled artefacts

  "**/*.log",          # noisy log files

  "secrets/*.txt"      # accidental secret files

]

This example is documented in the marker file specification, which explains the syntax and semantics of the [capture] section.

Lexical Matching and Enforcement

When a native command or hook emits a file-tool event, the capture code checks the event's path against the configured patterns. According to the akitaonrails/ai-memory source code in crates/ai-memory-hooks/src/capture_policy.rs, the should_capture function iterates over ignore_paths and rejects the event if any pattern matches.

// crates/ai-memory-hooks/src/capture_policy.rs – enforcement sketch
fn should_capture(path: &str, policy: &CapturePolicy) -> bool {
    // Reject if any ignore pattern matches
    if policy.ignore_paths.iter().any(|p| glob::Pattern::new(p).unwrap().matches(path)) {
        return false; // Event is excluded
    }
    true // Event will be captured
}

Because this check is lexical, it operates on the raw path string before any deeper inspection. It does not provide full data-loss prevention, but it does prevent noisy or large-volume files from flooding the capture pipeline. As documented in docs/mcp-install.md, native commands and generated plugins honour this policy at runtime.

Per-Repository Scope and Fallback Behavior

The policy is scoped per repository. Each repository can maintain its own marker file with its own exclusions, ensuring that unrelated projects do not influence each other's capture behaviour.

If a repository lacks a [capture] section or the ignore_paths array is empty, the policy remains inactive. In this fallback state, all file-tool events are captured as usual.

Why Capture Exclusions Matter

Capture exclusions improve the system in three specific ways:

• Performance – Ignoring large build artefacts such as target/ directories or log files reduces the volume of data that must be sanitized, stored, and indexed.
• Signal-to-noise – By dropping low-value events, the retrieval system focuses on meaningful observations, which improves relevance scores.
• Safety – While not a full DLP mechanism, the policy provides a first line of defence against accidental capture of sensitive or irrelevant files.

Testing Capture Exclusions with the CLI

You can test whether a specific path would be captured or rejected by using the --check-capture flag in the CLI. This allows you to validate your marker file rules without emitting real events.

# Using the CLI to test the policy

ai-memory hook --event file-tool --path src/main.rs --check-capture

# → "captured" (if src/main.rs is not ignored)

ai-memory hook --event file-tool --path target/debug/app --check-capture

# → "rejected by capture exclusions"

The README.md notes that supported agents enforce these exclusions by default, so validation through --check-capture helps ensure your local rules behave as expected.

Summary

• The capture exclusion policy is defined in docs/marker-file.md under the [capture] section using an ignore_paths array.
• The should_capture function in crates/ai-memory-hooks/src/capture_policy.rs enforces the policy by performing lexical glob matching against file-tool event paths.
• Matching events are rejected before they are spooled or sent to the server.
• The policy is per-repository; if no [capture] section exists, all events are captured.
• Exclusions improve performance, signal-to-noise ratio, and provide basic protection against accidental capture.

Frequently Asked Questions

Where is the capture exclusion policy defined?

The policy is defined in the nearest [capture] section of a repository's marker file at docs/marker-file.md. This file uses TOML syntax to declare an ignore_paths array containing glob patterns for paths that should be excluded.

How does the capture exclusion policy filter file-tool events?

When a file-tool event is emitted, the capture system checks the event's path against every pattern in ignore_paths via the should_capture function in crates/ai-memory-hooks/src/capture_policy.rs. If any glob pattern matches, the event is rejected and never spooled or transmitted.

What happens if a repository has no capture exclusions configured?

If the marker file lacks a [capture] section or the ignore_paths array is empty, the policy is inactive. In this case, ai-memory captures all file-tool events as usual without filtering.

Does the capture exclusion policy provide full data-loss prevention?

The policy does not provide full data-loss prevention. It is intentionally lexical and matches path strings before deeper analysis. It reduces noise and provides a basic safeguard, but it is not a comprehensive DLP mechanism.

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