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

> Discover how ai-memory handles pinned pages. Learn about immutable, decay-immune records that bypass the retention system for essential data.

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

---

**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](https://github.com/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:

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

This page will never decay...

```

In [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/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:

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

```

As implemented in [`wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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

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

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

```

### Slot Pages (Automatically Pinned)

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

```bash
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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md)** — Architectural documentation confirming pinned pages are exempt from all decay paths
- **[`docs/frontend-api.md`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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.