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

> Learn how to use capture exclusions in ai-memory with .ai-memory.toml. Configure ignore_paths to prevent specific files from being captured by the ai-memory pipeline.

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

---

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

```toml
[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:

```bash

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

```rust
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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/capture_policy.rs). You must explicitly enumerate the paths to exclude.

### Where should I place the [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.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.