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

> Discover how ai-memory's capture allowlist mode inverts default blocklist behavior, recording only explicitly opted-in repositories for targeted memory capture. Learn more.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-08-30

---

**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`](https://github.com/akitaonrails/ai-memory/blob/main/.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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) as the sole opt-in signal.

The implementation in [`crates/ai-memory-cli/src/commands/hook.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/hook.rs) (lines 541–563) demonstrates this logic:

```rust
// 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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/status.rs) (line 233) reflects this inverted behavior clearly:

```bash
$ 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:

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

```

## Opting In a Repository

Create a [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) file at the repository root. The file can be minimal—its mere presence satisfies the opt-in requirement:

```toml

# .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`](https://github.com/akitaonrails/ai-memory/blob/main/.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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/hook.rs) and [`crates/ai-memory-cli/src/commands/status.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/status.rs)
- Documentation at [`docs/marker-file.md`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/.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.