ai-memory ignore_paths Configuration: How to Exclude Files from Capture

[capture] ignore_paths is a capture-exclusion rule that tells the ai-memory server to drop any file-tool events matching specified glob patterns before they are spooled, queued, or transmitted, ensuring private paths never enter the memory store or LLM pipeline.

The akitaonrails/ai-memory repository implements a lifecycle event capture system that tracks codebase changes for AI-assisted development. Configuring ai-memory ignore_paths lets you define lexical boundaries that prevent sensitive directories and generated artifacts from being indexed in the Full-Text Search (FTS) database or converted to vector embeddings.

How ai-memory ignore_paths Filters Events

When the ai-memory hook processes a lifecycle event—such as a git diff output or a file search result—it first locates the nearest .ai-memory.toml marker file. The system compares the event's path against the ignore_paths array defined in the [capture] section. If any pattern matches, the event is discarded locally before network transmission occurs.

This pre-queue filtering means excluded files bypass the entire ingestion pipeline: no observation records are created, no wiki pages are generated, and no data reaches downstream LLM-driven consolidation. As implemented in docs/marker-file.md, this mechanism provides a lightweight boundary control that is not a full Data Loss Prevention (DLP) solution but effectively keeps specified paths out of the memory system.

Scope and Marker File Resolution

The exclusion rule applies to the nearest .ai-memory.toml file in the directory hierarchy. Critically, a marker file containing only a [capture] section does not reset workspace or project mappings; it functions solely as a capture-only boundary. This allows you to place granular exclusion rules in subdirectories without disrupting the broader repository configuration.

Pattern Syntax and Matching Rules

The ai-memory engine matches paths using simple glob syntax against lexically normalized absolute paths rooted at the marker file's directory.

• * matches any single path segment or character sequence within a segment
• ? matches exactly one character
• ** matches zero or more directory levels
• ~/ expands to the user's home directory
• Paths are evaluated as absolute paths normalized relative to the marker location

According to docs/marker-file.md, the matching occurs against the canonical absolute path, ensuring consistent behavior across different working directories.

Configuring ai-memory ignore_paths

Basic Exclusion Patterns

Create an .ai-memory.toml file in your repository root to exclude specific directories from capture:

# .ai-memory.toml

[capture]
ignore_paths = [
    "private/**",                # exclude entire private directory tree

    "~/personal-notes/**",       # exclude home directory notes

    "docs/adr/**",               # exclude architecture decision records

    "*.log",                     # exclude all log files

]

Capture-Only Markers

You can place marker files deeper in the hierarchy to apply exclusions only to specific sub-trees. These markers do not affect project resolution but still enforce capture rules:

# tools/.ai-memory.toml - applies only to tools/ subdirectory

[capture]
ignore_paths = ["tools/generated/**", "tools/tmp/*"]

Verifying Your Configuration

Validate your exclusion rules using the CLI before committing changes:

# Displays effective capture policy for current directory

ai-memory check-capture

This command outputs the resolved ignore_paths list and indicates whether sample paths would be dropped or captured.

Enabling Allow-List Mode

For high-security contexts, you can invert the logic so that no events are captured unless explicitly allowed through the filter mechanism:

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

In this mode, unrecognized paths and events failing the ignore filter are treated conservatively: recognized search and list tools are dropped, while malformed events become metadata-only entries without path data.

Summary

• [capture] ignore_paths prevents matching files from being indexed, embedded, or transmitted to the ai-memory server.
• Patterns use glob syntax (*, ?, **) matched against absolute paths rooted at the marker file.
• Exclusions are read from the nearest .ai-memory.toml without affecting workspace resolution.
• Events matching ignore patterns are dropped locally before network transport, ensuring zero exposure.
• Use ai-memory check-capture to validate policies and --capture-mode allowlist for restrictive capture environments.

Frequently Asked Questions

What happens if I don't configure ignore_paths?

If the [capture] section is missing or ignore_paths = [], the capture policy is inactive and ai-memory stores all recognized lifecycle events normally, as documented in docs/marker-file.md.

Does a capture-only marker affect project boundaries?

No. According to the source documentation, marker files containing only [capture] rules do not reset or alter workspace and project mappings. They strictly govern which file events are excluded from capture.

Can I use regular expressions instead of glob patterns?

No. The ai-memory configuration, as defined in crates/ai-memory-cli/templates/config.default.toml and docs/marker-file.md, supports only glob wildcards. Regular expression syntax is not supported in ignore_paths patterns.

How do I confirm a specific file would be excluded?

Run ai-memory check-capture in the target directory. This command reads the effective .ai-memory.toml configuration and reports whether paths would be dropped based on the current ignore_paths settings.

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