AI-Memory Capture Exclusion Patterns: How to Ignore Sensitive File Operations

AI-memory capture exclusion patterns allow you to prevent sensitive file operations from being recorded by configuring the ignore_paths list in your repository's .ai-memory.toml marker file.

The akitaonrails/ai-memory toolkit automatically captures lifecycle events such as tool calls and file writes, but storing observations of sensitive files or noisy build artifacts can violate privacy policies or clutter your data store. Understanding ai-memory capture exclusion patterns lets you define precise filters that drop unwanted events before they reach the storage layer.

Understanding the Capture Exclusion Policy

The Marker File Configuration (.ai-memory.toml)

Each repository defines its exclusion policy through a marker file named .ai-memory.toml located at the repository root. According to the docs/marker-file.md specification, this TOML file contains a dedicated [capture] section where you declare filtering rules. The only required key within this section is ignore_paths, which accepts a list of glob patterns or exact file paths that should be excluded from the capture pipeline.

How ignore_paths Filters Events

When the ai-memory system processes a file-tool activity, it evaluates the event path against your configured ignore_paths list. Any operation matching an entry in this list is dropped before it reaches the sanitiser and storage layers, meaning no observation is created for those operations. This lexical evaluation occurs as a fast first-line filter, ensuring that sensitive data never enters the sanitization or persistence workflow.

Sub-Agent Capture Control

In addition to path-based exclusions, the [capture] section supports a boolean flag drop_subagent_captures = "true" to suppress captures generated by sub-agents. This prevents auxiliary agents from flooding the system with noisy events while still allowing primary agent operations to be recorded.

Configuring Sensitive File Operation Exclusions

To keep credential files and temporary artifacts out of the AI-memory store, populate ignore_paths with specific patterns. Common exclusions include credential files like .env and secrets.json, build directories such as target/ and node_modules/, and large binary blobs like *.zip or *.tar.gz.

If the [capture] section is missing or ignore_paths is empty, capture remains active for all events. An empty list explicitly preserves the current non-filtered behavior.

# .ai-memory.toml – repository-level capture policy

[capture]

# Exclude credential files and temporary build directories

ignore_paths = [
    ".env",               # Environment files containing secrets

    "config/secrets.json",
    "target/**",          # Cargo build artifacts

    "node_modules/**",    # JavaScript dependencies

    "**/*.zip",           # Large binary archives

]

# Optional: stop sub-agents from generating captures

drop_subagent_captures = "true"

Verification and Programmatic Implementation

Before deploying your configuration, verify that your exclusions work as expected using the CLI. The --check-capture flag performs a dry-run that shows whether an event would be stored or ignored:

# Verify the current capture exclusions

ai-memory hook --event file_write \
    --path "./config/secrets.json" \
    --check-capture

# Output will indicate the event is ignored because of the ignore_paths rule

Under the hood, the system loads the marker file configuration once at startup. When writing custom hooks in Rust, you can access this policy through the configuration API as implemented in the source:

// Example of programmatic access when writing a custom hook
use ai_memory_hooks::sanitizer::Sanitizer;

let cfg = Config::load(); // reads the .ai-memory.toml file once
if cfg.capture.should_ignore(&event.path) {
    // Skip sending the observation to the store
    return;
}
let sanitized = Sanitizer::sanitize(event);
store_observation(sanitized);

This implementation ensures that sensitive file operations are excluded at the earliest possible stage, before any DLP checks or storage operations occur.

Summary

• ai-memory capture exclusion patterns are defined in .ai-memory.toml using the [capture] section and ignore_paths key.
• Exclusions are evaluated lexically before sanitization, ensuring sensitive data never enters the storage pipeline.
• The drop_subagent_captures flag allows separate control over noisy sub-agent events.
• Use ai-memory hook --check-capture to verify your exclusion rules before deployment.
• Default behavior captures all events when no exclusions are configured.

Frequently Asked Questions

What is the exact syntax for ignore_paths in ai-memory?

The ignore_paths key accepts a TOML array of strings containing glob patterns or exact paths relative to the repository root. Patterns follow standard glob syntax with ** for recursive matching and * for single-level wildcards. Each entry should be quoted and separated by commas within square brackets.

Does the exclusion apply to all lifecycle events?

Path-based exclusions in ignore_paths specifically filter file-tool activities and file operations as documented in docs/marker-file.md. Other lifecycle events such as prompt submissions are handled by different mechanisms, though the drop_subagent_captures setting affects captures generated by sub-agents across all event types.

How do I verify my capture exclusions are working?

Run the CLI command ai-memory hook --event <type> --path <file-path> --check-capture to test whether a specific file operation would be captured or dropped. This dry-run mode shows the effective policy without persisting any observations to the store.

Can I exclude sub-agent captures separately from file operations?

Yes. Set drop_subagent_captures = "true" in the [capture] section of .ai-memory.toml to suppress all captures generated by sub-agents while continuing to record operations from the primary agent. This operates independently of the ignore_paths filtering logic.

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