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

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 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, 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 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

---
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

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

// 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

// 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
• Soft-delete protection exists in 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, 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, 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 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.

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