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

> Learn how the capture exclusion policy in ai-memory filters file tool events by matching paths against glob patterns in your marker file. Prevent unwanted event recording.

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

---

**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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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.

```toml

# 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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-hooks/src/capture_policy.rs), the `should_capture` function iterates over `ignore_paths` and rejects the event if any pattern matches.

```rust
// 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`](https://github.com/akitaonrails/ai-memory/blob/main/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.

```bash

# 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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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.