# How to Configure Capture Exclusions Using .ai-memory.toml Marker Files

> Learn how to configure capture exclusions using .ai-memory.toml marker files. Exclude specific files from observation logging by defining ignore paths in your TOML configuration.

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

---

**You configure capture exclusions by creating a [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) file in your repository root (or any parent directory) and adding a `[capture]` section containing an `ignore_paths` array of glob patterns that match files you want to exclude from observation logging.**

The `ai-memory` system automatically records file-tool activity such as edits and searches to build context-rich memories for AI agents. When you need to prevent sensitive data, temporary files, or large generated artifacts from being captured, the akitaonrails/ai-memory repository provides a marker-based exclusion system that evaluates patterns locally before any data leaves your machine.

## Placement and Hierarchy of Marker Files

Create or edit [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) anywhere on the walk-up path from your working directory. The tool searches upward from the current working directory and uses the **nearest** marker file found; sections are **not merged** with outer markers. This means a [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) in a subdirectory completely overrides any configuration in parent directories.

According to [`docs/marker-file.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md) (lines 59-84), this non-merging behavior ensures that child projects can define strict local policies without inheriting potentially inappropriate exclusion patterns from ancestor directories.

## Defining Capture Exclusions

### The [capture] Section and ignore_paths Array

Add a `[capture]` section to your marker file containing an `ignore_paths` array. Each entry is a glob pattern supporting only `*`, `?`, and `**` wildcards. Patterns are interpreted **relative to the directory containing the marker file** and match against lexically normalized paths.

```toml
[capture]
ignore_paths = [
    "private/**",          # any file under a `private` folder

    "~/personal-notes/**", # expands to $HOME/personal-notes

    "*.log",
    "temp/?it.txt"
]

```

As implemented in the source code and documented in [`docs/marker-file.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md) (lines 75-81), the `~/` prefix automatically expands to the user's home directory, and patterns must use forward slashes on all platforms.

### Pattern Matching Rules

Pattern evaluation follows strict lexical rules:

- Only `*`, `?`, and `**` wildcards are supported; regular expressions are not permitted.
- Patterns match the **entire** normalized path, not substrings. For example, `secret` will not match [`/path/secret/file.txt`](https://github.com/akitaonrails/ai-memory/blob/main//path/secret/file.txt), but `**/secret/**` will.
- **POSIX systems**: Matching is case-sensitive.
- **Windows**: Matching is ASCII-case-insensitive.
- Forward slashes are required on all platforms; the system normalizes paths before matching.

## How Exclusions Are Enforced

Capture exclusions are enforced **only by native `ai-memory hook` commands**—the binaries installed by the `install-hooks` script. When a hook receives an event containing a file path, it checks the `ignore_paths` list from the nearest marker file. If any pattern matches, the entire event is **dropped locally** before being spooled, queued, sent over the network, or stored on the server.

As noted in [`docs/marker-file.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md) (lines 103-110), generated OpenCode/OMP/Pi/OpenClaw plugins and legacy script-based installers do **not** apply this policy unless they explicitly invoke the native hook binary. The core enforcement logic resides 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) and [`hooks/_lib.sh`](https://github.com/akitaonrails/ai-memory/blob/main/hooks/_lib.sh).

## Testing Policies Without Capturing

You can preview exclusion decisions using the `--check-capture` flag, which simulates the capture decision without affecting the spool or revealing payload content.

```bash
printf '{"session_id":"test","cwd":"/home/alice/project","tool_name":"Edit","tool_input":{"path":"~/secrets/api_key.txt"}}' \
  | ai-memory hook --event post-tool-use --agent claude-code \
      --server-url http://127.0.0.1:49374 --check-capture

```

Expected output:

```json
{"status":"dropped","reason":"path matched ignore_paths"}

```

This command, documented in [`docs/marker-file.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md) (lines 18-26), allows you to verify that sensitive paths are correctly excluded before committing the configuration.

## Allow-List Mode Configuration

By default, the presence of a marker file narrows capture scope. To require an explicit opt-in where only directories containing [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) generate capture events, install hooks with the `--capture-mode allowlist` flag:

```bash
ai-memory install-hooks --apply --capture-mode allowlist

```

In this mode, repositories without marker files are silently ignored, while capture exclusions defined within existing markers continue to apply on top of the allow-list filtering.

## Practical Configuration Examples

### Excluding Generated Artifacts

Place this [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) at your repository root to exclude logs and temporary directories:

```toml
workspace = "example"
project = "demo"

[capture]
ignore_paths = ["temp/**", "*.log", "build/**"]

```

Any file under `temp/` or `build/`, or any file ending with `.log`, will be dropped locally and never transmitted to the server.

### Protecting Home Directory Secrets

To exclude sensitive files regardless of which repository you're working in, place a marker file in your home directory:

```toml
[capture]
ignore_paths = ["~/secrets/**", "~/.ssh/**"]

```

This excludes paths like [`/home/alice/secrets/api_key.txt`](https://github.com/akitaonrails/ai-memory/blob/main//home/alice/secrets/api_key.txt) even when editing projects located elsewhere.

### Project-Specific Private Notes

For a subdirectory that contains private documentation:

```toml
[capture]
ignore_paths = ["private-notes/**", "**/local-config.json"]

```

## Summary

- Create [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) on the walk-up path from your working directory; the nearest file wins and does not merge with parent configurations.
- Add a `[capture]` section with an `ignore_paths` array containing glob patterns (`*`, `?`, `**`) to exclude specific paths relative to the marker file's location.
- Patterns support `~` home directory expansion, must use forward slashes on all platforms, and match entire paths on POSIX (case-sensitive) or Windows (case-insensitive).
- Exclusions are enforced only by native `ai-memory hook` binaries 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), dropping matching events before network transmission.
- Test configurations using `ai-memory hook --check-capture` to verify paths are dropped without affecting the spool or revealing payload content.
- Use `--capture-mode allowlist` during hook installation to restrict capture to repositories containing marker files.

## Frequently Asked Questions

### Does ai-memory merge multiple .ai-memory.toml files found in parent directories?

No. According to the source documentation in [`docs/marker-file.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md) (lines 59-84), the system selects the nearest marker file on the walk-up path and does not merge its sections with outer markers. This allows subdirectories to override parent configurations completely without inheriting unwanted exclusion rules.

### Can I use regular expressions in ignore_paths patterns?

No. The `ignore_paths` array accepts only glob patterns using `*`, `?`, and `**` wildcards. These patterns match the entire lexically normalized path rather than substrings, and they are evaluated without regex support 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) and [`hooks/_lib.sh`](https://github.com/akitaonrails/ai-memory/blob/main/hooks/_lib.sh).

### Will capture exclusions work with legacy hook scripts or third-party plugins?

No. Capture exclusions are enforced only by native `ai-memory hook` commands installed via the official installer. Generated plugins for OpenCode, OMP, Pi, or OpenClaw, as well as legacy script-based installers, do not apply exclusion policies unless they explicitly invoke the native hook binary.

### How does path matching differ between Windows and Linux?

On POSIX systems (Linux, macOS), pattern matching is case-sensitive. On Windows, matching is ASCII-case-insensitive. Both platforms require forward slashes in patterns; the system normalizes paths internally before matching against your `ignore_paths` entries, as detailed in [`docs/marker-file.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md) (lines 75-81).