# How Pinned Pages Are Handled by the ai-memory Decay Policy: Complete Immunity Guide

> Discover how pinned pages in akitaonrails ai-memory bypass decay policies. Learn how to ensure your important data remains accessible and immune to automatic deletion.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: deep-dive
- Published: 2026-08-26

---

**Pinned pages in ai-memory are completely exempt from the automatic forget-sweep decay process, whether marked manually via front-matter (`pinned: true`) or automatically as slot pages in the `_slots/` directory.**

The ai-memory system implements an intelligent decay policy to age out stale content, but certain critical pages must remain permanently accessible. Understanding how pinned pages handled by the ai-memory decay policy ensures your essential knowledge survives routine cleanup operations while ephemeral content is properly pruned.

## Decay Candidate Exclusion in the Reader Layer

The decay process begins in [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs) within the `ReaderPool::decay_candidates` function. When the background decay job queries for candidates, it explicitly filters out any row where the pinned flag is set to true.

According to the source code at line 7091, the implementation contains a clear invariant in the comments: the pinned flag being true means "never decay". This ensures that pinned pages never appear in the candidate set, are never converted to decay tombstones, and survive the cleanup step untouched.

## Write-Time Protection in the Operations Layer

Even if a pinned page somehow reached the decay logic, the write operations provide a secondary safeguard. In [`crates/ai-memory-store/src/ops.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/ops.rs), the `soft_delete_for_decay_if_latest` function checks the pinned flag before attempting any soft-delete operation.

At line 1731, the implementation returns immediately without modifying the row if the pinned attribute is true. This defensive programming ensures that pinned content cannot be accidentally aged out, even if the reader-layer filter were bypassed.

## Automatic Pinning for Slot Pages

The system provides two mechanisms for pinning: explicit front-matter declaration and automatic slot classification.

### Explicit Front-Matter Pinning

Users can mark any page as decay-immune by adding `pinned: true` to the YAML front-matter of a Markdown file. This manual flag persists through all decay cycles until explicitly removed by an operator.

### The `_slots/` Directory Convention

Pages residing under the special `_slots/` directory receive automatic pinning at write-time. In [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs) at line 3280, the wiki layer forces the `pinned: true` flag before persisting slot pages, treating these operator-curated shortcuts as permanent fixtures. Line 560 of the same file handles the actual persistence of the pinned flag into page metadata during normal write operations.

## Practical Implementation Examples

Below are concrete implementations demonstrating decay immunity patterns in ai-memory.

### Pinning via Front-Matter

```yaml
---
title: "Critical Architecture Decision"
tier: semantic
pinned: true          # This flag makes the page decay-immune

---
This content will persist indefinitely regardless of access patterns.

```

### Creating Auto-Pinned Slot Pages

```rust
let slot_path = PagePath::new("_slots/daily-focus.md").unwrap();
let mut req = WritePageRequest::new(
    slot_path.as_str(),
    "Current sprint objectives",
    json!({ "title": "Daily Focus", "tier": "working" })
);
// The wiki layer automatically sets pinned: true for _slots/ paths
wiki.write_page(req).await?;

```

### Verifying Decay Exclusion

```rust
// Query decay candidates - pinned pages are omitted
let candidates = store.reader.decay_candidates(ws, proj).await?;
assert!(!candidates.iter().any(|c| c.pinned), 
        "Pinned pages should never appear in decay candidates");

```

### Attempting Decay on Pinned Content

```rust
// This operation silently succeeds without touching the row
let result = ops::soft_delete_for_decay_if_latest(
    &mut conn,
    page_id,
    &DecayParams::default(),
); // Returns Ok(()) immediately if the page is pinned

```

## Summary

- **Pinned pages are excluded** from `ReaderPool::decay_candidates` queries in [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs)
- **Soft-delete protection** exists in [`crates/ai-memory-store/src/ops.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/ops.rs) where `soft_delete_for_decay_if_latest` aborts without modifying pinned rows
- **Manual pinning** occurs via front-matter `pinned: true` for any page requiring decay immunity
- **Automatic pinning** applies to the `_slots/` directory via [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs), forcing the flag at write-time
- **Permanent retention** is guaranteed unless an explicit un-pin operation removes the flag

## Frequently Asked Questions

### How do I prevent a specific page from being removed by ai-memory's decay policy?

Add `pinned: true` to the YAML front-matter of your Markdown file. This flag makes the page completely invisible to the decay candidate selection process in [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs), ensuring it persists indefinitely regardless of access patterns or age.

### What is the difference between regular pinned pages and slot pages?

Slot pages are automatically pinned by the system when stored in the `_slots/` directory, as implemented in [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs) at line 3280. Regular pinned pages require manual front-matter configuration, but both receive identical decay immunity through the `pinned` database flag checked by the decay policy.

### Can a pinned page ever be deleted by the decay system?

No. The decay policy contains multiple safeguards: `ReaderPool::decay_candidates` excludes pinned rows from the candidate list (line 7091), and `soft_delete_for_decay_if_latest` checks the flag before any deletion (line 1731). Only explicit un-pinning or manual deletion operations can remove pinned content.

### Does pinning affect the semantic tier or search indexing of a page?

No, pinning only affects the decay lifecycle management. The semantic tier, vector embeddings, and search indexability remain controlled by separate metadata fields like `tier`. Pinned pages participate fully in the knowledge graph and embedding calculations while being exempt from the automatic forget-sweep.