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

You configure capture exclusions by creating a .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 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 in a subdirectory completely overrides any configuration in parent directories.

According to 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.

[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 (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, 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 (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 and 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.

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:

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

This command, documented in 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 generate capture events, install hooks with the --capture-mode allowlist flag:

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 at your repository root to exclude logs and temporary directories:

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:

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

This excludes paths like /home/alice/secrets/api_key.txt even when editing projects located elsewhere.

Project-Specific Private Notes

For a subdirectory that contains private documentation:

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

Summary

• Create .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, 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 (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 and 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 (lines 75-81).

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