# How Capture Exclusions Work with .ai-memory.toml Marker Files

> Learn how .ai-memory.toml marker files enable capture exclusions using glob patterns in the ignore_paths array. Control what gets captured efficiently.

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

---

**The [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) marker file lets you exclude specific file paths from being captured using glob patterns defined in an `ignore_paths` array under the `[capture]` section.**

The `akitaonrails/ai-memory` repository provides a local-first memory system for AI-assisted development that respects repository boundaries through marker files. Understanding how to configure capture exclusions ensures sensitive files never leave your machine while still allowing productive tracking of your coding sessions.

## Configuring the [capture] Section

To exclude specific paths from capture, add a `[capture]` table to your [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) file with an `ignore_paths` array containing glob patterns.

```toml
[capture]
ignore_paths = [
  "private/**",
  "~/personal-notes/**",
  "secrets/*_key.txt"
]

```

According to the marker file definition in [`docs/marker-file.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md), these patterns prevent matching events from being stored in the local spool or transmitted to the server. If the section is missing or `ignore_paths` is an empty array, capture proceeds normally without exclusions.

## Marker Resolution and Precedence

The system uses a **nearest marker wins** policy. When the `ai-memory hook` command runs, it walks up the directory tree from the current working directory and uses the first [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) it encounters.

- Only that specific file's `[capture]` section applies
- Multiple markers do **not** merge their configurations
- If the found marker lacks a `[capture]` section, no exclusions are applied

This behavior is implemented 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), where the CLI resolves the marker path before evaluating capture policy.

## Pattern Matching Semantics

Patterns in `ignore_paths` follow specific matching rules defined in the hook implementation:

- **Full path matching**: Patterns match against fully normalized absolute paths, not substrings
- **Glob support**: Uses standard glob syntax with `*` (any characters), `?` (single character), and `**` (recursive directory matching)
- **Root anchoring**: Patterns are rooted at the marker file's directory location
- **Home expansion**: `~/` expands to the user's home directory
- **Case sensitivity**: POSIX systems use case-sensitive matching; Windows uses ASCII case-insensitive matching

A pattern like `secrets/**` excludes all files under any `secrets` directory relative to the marker location, while `~/private/**` excludes the private folder in your home directory regardless of where the marker sits.

## Enforcement Points in the Pipeline

Capture exclusions are enforced by the native `ai-memory hook` command before events reach storage. When a file-tool event matches any exclusion pattern, the hook **drops the event locally** immediately.

This filtering occurs:
- Before writing to the local spool
- Before queuing for network transmission
- Before server storage

The enforcement logic in [`hook_capture.rs`](https://github.com/akitaonrails/ai-memory/blob/main/hook_capture.rs) processes the event against the resolved marker's exclusion list. When the `--capture-mode allowlist` flag is used during installation, the presence of a marker file opts the repository into capture, but the same `[capture]` exclusions still apply to filter which events within that repository are actually stored.

## What Gets Filtered vs. Preserved

Only events with recognized **file-tool schemas** are subject to capture exclusions. The system specifically checks the `tool_input.path` or similar path attributes in events like `Edit`, `Read`, or `Write` operations.

The following are **not** affected by capture exclusions:
- Prompts and assistant messages without file paths
- Tool events lacking recognizable path attributes
- Metadata-only events like session starts or heartbeats

If a tool operates on an excluded path, the entire event is discarded; however, subsequent operations on non-excluded paths proceed normally.

## Testing Capture Decisions Locally

Use the `--check-capture` flag to verify whether a specific payload would be captured or dropped without actually storing it:

```bash
printf '{"session_id":"demo","cwd":"/example","tool_name":"Edit","tool_input":{"path":"docs/example.md"}}' |
  ai-memory hook --event post-tool-use --agent claude-code \
    --server-url http://127.0.0.1:49374 --check-capture

```

This outputs the disposition (kept or dropped) and metadata, allowing you to validate your exclusion patterns before committing sensitive files to the exclude list.

## Summary

- **Add exclusions** using the `[capture]` table with `ignore_paths` in [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml)
- **Nearest marker wins**: The first [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) found walking up from the working directory controls exclusions exclusively
- **Glob patterns** support `*`, `?`, `**`, and `~/` expansion against normalized absolute paths
- **Local enforcement** happens in [`hook_capture.rs`](https://github.com/akitaonrails/ai-memory/blob/main/hook_capture.rs) before events reach storage or the network
- **File-only filtering** affects only tool events with identifiable paths; prompts and messages pass through
- **Use `--check-capture`** to validate patterns without actual data transmission

## Frequently Asked Questions

### How do I exclude an entire directory from ai-memory capture?

Add a recursive glob pattern under the `[capture]` section in your marker file. Use `directory-name/**` to exclude all files and subdirectories within that folder relative to the marker location, or `~/directory-name/**` to exclude paths in your home directory.

### What happens if I have multiple .ai-memory.toml files in parent directories?

The system uses the **nearest marker only**. When processing an event, `ai-memory hook` walks upward from the current working directory and stops at the first [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) it finds. That file's `[capture]` rules apply exclusively; parent marker configurations are ignored and do not merge.

### Do capture exclusions work in allowlist mode?

Yes. When hooks are installed with `--capture-mode allowlist`, a repository must contain an [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) file to opt-in to capture at all. Once opted-in, the same `[capture]` section with `ignore_paths` still filters which specific file events within that repository are actually stored. The marker enables capture for the repository, while the exclusions limit what gets captured.

### Can I test if my exclusion patterns work without saving data?

Yes. Use the `--check-capture` flag with the `ai-memory hook` command. Pipe a JSON payload representing your event to the command with this flag, and it will print whether the event would be kept or dropped based on the current marker configuration without persisting anything to the database or server.