How Pinned Pages Are Handled in ai-memory: Complete Technical Guide

Pinned pages in ai-memory are marked with pinned: true in front-matter and are treated as immutable, decay-immune records that bypass the entire retention system.

In ai-memory, the pinned page mechanism provides a way to protect critical content from automatic deletion. When a page carries the pinned: true flag—either explicitly in its front-matter or implicitly by residing in the _slots/ directory—it becomes exempt from all decay paths, periodic forget-sweeps, and automated mutations. This article explains the implementation details according to the akitaonrails/ai-memory source code.

How the Pinned Flag Is Set and Preserved

The pinned attribute flows through the system via three pathways: explicit front-matter declaration, API request parameters, and automatic slot detection.

Explicit Front-Matter Declaration

Front-matter is the single source of truth for pinned status. When you create or update a page, include pinned: true in the YAML front-matter block:

---
title: "System Architecture"
pinned: true
---

This page will never decay...

In crates/ai-memory-wiki/src/wiki.rs, the canonicalize_index_frontmatter function re-applies this flag during every re-index, ensuring the persisted state cannot be accidentally lost.

API Request Parameters

The memory_write_page call accepts a pinned field in its JSON payload:

{
  "path": "notes/important.md",
  "body": "Critical content",
  "pinned": true
}

As implemented in wiki.rs, the server stores this flag and returns it unchanged in all subsequent queries, regardless of TTL or decay configuration.

Automatic Slot Pinning

Pages under the _slots/ directory receive implicit pinned status. The is_slot_path(&path) helper returns true for any path starting with _slots/, and the wiki engine sets pinned: is_slot_path(&path) automatically. This protects essential configuration such as persona definitions without requiring manual front-matter edits.

Retention Engine Behavior for Pinned Pages

The decay system contains an explicit bypass for pinned content. According to docs/ARCHITECTURE.md:

"Pinned pages (pinned: true in frontmatter) are exempt from all decay paths."

This means:

• Decay formula exclusion — Pinned pages never lose relevance scores over time
• Forget-sweep immunity — Periodic cleanup jobs skip pinned records entirely
• Permanent storage — Original Markdown source is preserved indefinitely

The retention engine checks the metadata flag before applying any retention policy, making pinned pages a first-class kind that exists outside the standard lifecycle.

Code Examples for Working with Pinned Pages

Creating a Pinned Page via Rust API

use ai_memory_wiki::Wiki;
use serde_json::json;

let wiki = Wiki::new(...).await?;
let path = "notes/important.md".parse()?;

let req = wiki::WritePageRequest {
    path: path.clone(),
    body: "Critical design decision".into(),
    frontmatter: json!({
        "title": "Critical Design",
        "pinned": true
    }),
    ..Default::default()
};

wiki.write_page(req).await?;

Verifying Pinned Status

let meta = wiki.page_meta("default", "scratch", "notes/important.md").await?;
println!("Pinned? {}", meta.pinned);   // → true

Slot Pages (Automatically Pinned)

let slot_path = PagePath::new("_slots/user_preferences.md")?;
let meta = wiki.page_meta("default", "scratch", slot_path.as_str()).await?;
assert!(meta.pinned);   // true without explicit front-matter

CLI Usage

ai-memory write_page notes/important.md \
  --body "Critical design decision" \
  --frontmatter '{"title":"Critical Design","pinned":true}'

Key Implementation Files

Understanding pinned page handling requires familiarity with these source locations:

• crates/ai-memory-wiki/src/wiki.rs — Core implementation where pinned: meta.pinned and pinned: is_slot_path(&path) assignments occur; handles canonicalize_index_frontmatter
• docs/ARCHITECTURE.md — Architectural documentation confirming pinned pages are exempt from all decay paths
• docs/frontend-api.md — JSON API schema documenting the pinned field in request/response payloads

Summary

• Pinned pages are created via pinned: true in front-matter or automatic _slots/ directory detection
• Decay immunity — The retention engine skips pinned pages entirely, preserving them permanently
• Front-matter authority — The canonicalize_index_frontmatter function in wiki.rs guarantees pinned status survives re-indexing
• Slot protection — All _slots/ pages are implicitly pinned via is_slot_path(&path)
• API consistency — The memory_write_page endpoint respects and persists the pinned flag from JSON payloads

Frequently Asked Questions

How do I prevent a page from being deleted by the forget-sweep?

Add pinned: true to the page's front-matter. According to the ARCHITECTURE.md documentation, pinned pages are exempt from all decay paths and will never be removed by automated cleanup processes.

What happens if I omit the pinned flag during a page update?

The canonicalize_index_frontmatter function in wiki.rs re-reads the front-matter during every re-index, so the persisted flag from the stored Markdown source takes precedence. However, API writes that explicitly set pinned: false can override this if the request is constructed to do so.

Are slot pages automatically pinned even without front-matter?

Yes. Any page stored under _slots/ is automatically assigned pinned: true via the is_slot_path(&path) check in wiki.rs. This protects configuration data such as persona definitions without requiring manual flag management.

Can pinned pages still be deleted manually?

The source analysis does not indicate that pinned status prevents manual deletion—it only blocks automated decay and forget-sweeps. Administrative deletion would likely still be possible through direct filesystem or API operations, though this is not explicitly documented in the analyzed files.

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