How the Capture Allowlist Mode in ai-memory Inverts the Default Blocklist Behavior

Allowlist mode in ai-memory flips the default capture logic from "record everything except ignored paths" to "record nothing unless the repository explicitly opts in via a .ai-memory.toml marker file."

By default, ai-memory operates on a blocklist principle: it captures all file-tool activity across repositories, using the [capture] ignore_paths setting only to exclude specific paths. The capture allowlist mode inverts this behavior entirely. Instead of capturing by default, the system treats all repositories as excluded until they deliberately signal participation through a marker file.

How Blocklist Mode Works by Default

In standard operation, ai-memory assumes universal capture. The [capture] ignore_paths configuration in a marker file merely filters out unwanted directories or patterns.

This means:

• Every repository is automatically enrolled in capture
• The blocklist specifies what to skip
• No marker file is required for capture to begin

According to the marker-file documentation at docs/marker-file.md (line 139), this is the baseline behavior most users encounter first.

The Allowlist Inversion: Opt-In Capture

Allowlist mode reverses every assumption of the default. When enabled, the system captures nothing by default and treats the presence of .ai-memory.toml as the sole opt-in signal.

The implementation in crates/ai-memory-cli/src/commands/hook.rs (lines 541–563) demonstrates this logic:

// In crates/ai-memory-cli/src/commands/hook.rs
if allowlist_mode && !marker_present {
    // Skip emitting capture events for this repository
    return Ok(());
}

Without the marker file, the hook command emits no capture events for that repository—regardless of what file-tool activity occurs.

Checking Allowlist Status

The status command in crates/ai-memory-cli/src/commands/status.rs (line 233) reflects this inverted behavior clearly:

$ ai-memory status
Repository: /path/to/project
Capture mode: allowlist
Marker file: missing → capture disabled

Repositories missing the marker are explicitly reported as ignored, making the exclusion transparent to developers.

Enabling Allowlist Mode

Activate allowlist mode during hook installation:

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

Opting In a Repository

Create a .ai-memory.toml file at the repository root. The file can be minimal—its mere presence satisfies the opt-in requirement:

# .ai-memory.toml

# Empty file – its mere presence enables capture under allowlist mode

You may add configuration later, but no content is required for initial opt-in.

Comparing the Two Modes

Aspect	Blocklist (Default)	Allowlist
Default capture behavior	Capture everything	Capture nothing
Marker file role	Optional configuration file	Mandatory opt-in signal
Without marker file	Full capture enabled	Explicitly excluded
Use case	Trusted environments, broad monitoring	Restricted environments, explicit consent

Summary

• Blocklist mode captures all repositories by default, filtering only via ignore_paths
• Allowlist mode excludes all repositories by default, requiring .ai-memory.toml as opt-in proof
• The marker file's presence—not its content—determines eligibility under allowlist mode
• Core logic resides in crates/ai-memory-cli/src/commands/hook.rs and crates/ai-memory-cli/src/commands/status.rs
• Documentation at docs/marker-file.md defines the semantic contract

Frequently Asked Questions

How do I know if my repository is being captured in allowlist mode?

Run ai-memory status in your repository directory. If the marker file is missing, you'll see "capture disabled." If present, capture proceeds normally according to your configuration.

Can I use allowlist mode for some repositories and blocklist for others?

No—the capture mode is set at the ai-memory installation level via install-hooks --capture-mode allowlist. The mode applies globally to all repositories processed by that installation.

Does the .ai-memory.toml file need specific content to opt in?

No. As implemented in the hook command logic, the file's mere presence satisfies the opt-in requirement. You can leave it empty or populate it with [capture] configuration as needed.

What happens to historical captures when switching to allowlist mode?

Switching modes only affects future capture events. Existing captured data remains in storage; the mode change controls whether new file-tool activity generates capture records based on marker file presence.

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