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

The .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 file with an ignore_paths array containing glob patterns.

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

According to the marker file definition in 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 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, 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 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:

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
• Nearest marker wins: The first .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 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 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 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.

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