# How the Authority-Aware Recall System Weights Rules, Decisions, and Procedures in ai-memory

> Discover how the ai-memory recall system weights rules decisions and procedures using a bounded authority multiplier for accurate information retrieval.

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

---

**The ai-memory recall system applies a bounded authority multiplier after fusing search scores, with Rules receiving the highest weight, Decisions a high tier below Rules, and Procedures defaulting to neutral unless tagged.**

The **authority-aware recall system** in [akitaonrails/ai-memory](https://github.com/akitaonrails/ai-memory) re-ranks search results based on page type and metadata, ensuring critical organizational knowledge surfaces first. This article explains how the system assigns differential weights to **Rules**, **Decisions**, and **Procedures** through a multiplicative authority factor applied after score fusion.

## The Three-Stage Recall Pipeline

The query pipeline documented in [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md) operates in distinct phases:

1. **Candidate generation** — FTS5 full-text search, lexical-entity matching, and optional vector similarity run in parallel
2. **Score fusion** — Reciprocal Rank Fusion (RRF) combines stream scores into a single `fused_score`
3. **Authority adjustment** — A bounded multiplier modifies the fused score based on page kind and metadata

The authority multiplier is the final ranking determinant, capable of elevating or suppressing results regardless of their lexical or semantic match quality.

## Page Kind Hierarchy and Authority Tiers

The `PageKind` enum defined in [`crates/ai-memory-consolidate/src/types.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/types.rs) drives the base authority assignment. The system recognizes a clear hierarchy:

| Page Kind | Directory Pattern | Authority Treatment |
|-----------|-------------------|---------------------|
| **Rule** | `_rules/*.md` | **Canonical-source tier** — strongest multiplier (typically 2.0 or higher) |
| **Decision** | `_decisions/*.md` | **High-authority tier** — elevated multiplier, subordinate only to Rules |
| **Procedure** | `_procedures/*.md` | **Default tier** — neutral multiplier (1.0) unless metadata overrides |
| **Standard page** | Any other path | Baseline authority, adjustable via front-matter tags |

This hierarchy reflects organizational reality: Rules represent invariant constraints, Decisions record binding commitments, and Procedures describe operational steps that may change with context.

## Metadata Tags That Modify Authority

Beyond base page kind, front-matter metadata provides fine-grained authority control. The parser in [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs) extracts these tags and computes a composite factor:

- **`canonical: true`** — Modest boost for definitive sources
- **`active: true`** — Elevates currently valid content over deprecated versions
- **`pinned: true`** — Forces minimum authority floor regardless of other factors
- **`source-of-truth`** tag — Marks authoritative references
- **`tier: X`** — Explicit numeric tier override (1-5 scale)
- **`low`** or **`experimental`** — Suppresses to neutral or below
- Missing authority tags — Defaults to 1.0 multiplier

The authority system is **bounded and saturating** — multipliers cannot inflate without limit. Tests in [`reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/reader.rs) (lines 7628-7635) verify that extreme values are clamped to prevent any single page from overwhelming results.

## Implementation: The Rank Adjustment Formula

In [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs), the authority adjustment occurs after fusion:

```rust
// After RRF fusion produces fused_score
hit.rank = authority.adjust_rank(hit.rank);

```

The `Authority::adjust_rank` implementation transforms scores as follows:

```rust
// Simplified from reader.rs lines 190-211, 404-409
fn adjust_rank(&self, rank: f64) -> f64 {
    let factor = self.compute_factor(); // Based on kind + metadata
    // Higher factor pushes rank more negative (higher in results)
    -(self.fused_score * factor)
}

```

The assertion in [`store/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/store/src/lib.rs) (lines 5692-5696) confirms the arithmetic relationship:

```rust
assert!(rank + fused * authority ≈ 0.0);

```

This negative-rank convention follows SQLite FTS5 ordering, where lower numbers appear first.

## Practical Code Examples

### Querying with Authority Awareness

```rust
use ai_memory::Client;

let client = Client::new("/path/to/memory.db").await?;

// Query returns authority-adjusted results automatically
let result = client.memory_query("deployment rollback procedure")
    .explain(true)  // Include per-hit scoring details
    .await?;

for hit in &result.hits {
    println!("Title: {}", hit.title);
    println!("Page kind: {:?}", hit.page_kind);
    println!("Fused score: {:.3}", hit.score_details.fused);
    
    if let Some(factor) = hit.score_details.authority {
        println!("Authority factor: {:.2}x", factor);
    }
}

```

A Rule titled "Mandatory Rollback Protocol" with `canonical: true` and `pinned: true` would outrank a Procedure with identical lexical relevance but default authority.

### Creating High-Authority Rule Pages

```rust
let rule_content = r#"---
title: "Production Access Requires MFA"
kind: Rule
canonical: true
pinned: true
tags: ["source-of-truth", "security", "tier:1"]
---

# Rule: PROD-001

All access to production environments **must** use multi-factor authentication.
Violations require immediate security review.
"#;

client
    .write_page("_rules/prod-access-mfa.md", rule_content)
    .await?;

```

This page receives the maximum authority multiplier, ensuring it appears first for any query mentioning "production access" or "MFA".

### Creating Authority-Tiered Decisions

```rust
let decision_content = r#"---
title: "Adopt Rust for New Services"
kind: Decision
active: true
decided: 2024-01-15
tags: ["tier:2"]
---

# Decision: ARCH-2024-003

New backend services shall use Rust as the primary implementation language.
This decision supersedes previous Python-first guidance.
"#;

client
    .write_page("_decisions/rust-adoption.md", decision_content)
    .await?;

```

Decisions with `active: true` receive elevated authority, though still below canonical Rules.

### Standard Procedures Without Authority Boost

```rust
let procedure_content = r#"---
title: "Onboarding Checklist"
kind: Procedure
---

# New Hire Onboarding

1. Complete HR paperwork
2. Request laptop via IT ticket
3. Join #engineering Slack channel
"#;

client
    .write_page("_procedures/onboarding.md", procedure_content)
    .await?;

```

Procedures without authority metadata rank purely on content relevance.

## Architecture Documentation Sources

The behavior described above is grounded in these source locations:

- **[`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md)** — Describes "bounded authority multiplier adjusts relevance using canonical" (line 117)
- **[`docs/usage.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/usage.md)** — Table documenting `memory_query` pipeline with "followed by a bounded kind/tier/pinned/tag authority adjustment" (lines 80-109)
- **[`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs)** — Authority extraction, candidate window limits, and rank adjustment (lines 190-211, 404-409)
- **[`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs)** — Unit tests verifying bounded behavior and rank formula (lines 7628-7635)
- **[`crates/ai-memory-consolidate/src/types.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/types.rs)** — `PageKind` enum definitions

## Summary

The **authority-aware recall system** in ai-memory implements a two-layer weighting mechanism:

- **Base layer**: Page kind assigns Rules highest authority, Decisions high authority, and Procedures neutral authority
- **Adjustment layer**: Front-matter metadata (`canonical`, `active`, `pinned`, `tier`, `source-of-truth`) fine-tunes the multiplier up or down

The final rank calculation `-(fused_score × authority_factor)` ensures that organizational governance documents surface above operational content when relevance is otherwise comparable. The system is bounded to prevent authority gaming and saturates extreme values for stability.

## Frequently Asked Questions

### How does the system prevent low-quality Rules from dominating results?

The authority multiplier is **bounded and saturating** as implemented in [`reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/reader.rs). Even maximum authority metadata cannot force a page with poor semantic or lexical match quality to the top if its fused score is near zero. The fusion stage provides the relevance foundation; authority provides the ranking tiebreaker among viable candidates.

### Can I override a Rule's authority with explicit metadata?

No. The `PageKind::Rule` classification from the `_rules/` directory path establishes a floor authority that metadata can only augment, not reduce. However, you can mark Rules as `active: false` or add `deprecated` tags to suppress them in practice without removing the base authority elevation.

### What happens when multiple pages have identical authority factors?

When authority multipliers produce equal ranks, the system falls back to the original fused score from RRF, then to recency if available, and finally to deterministic page ID ordering. This ensures stable, predictable result ordering without arbitrary randomness.

### Does vector similarity search respect authority weighting?

Yes. Vector similarity feeds into the **fusion** stage, producing one component of the `fused_score`. The authority multiplier is applied **after** fusion, so vector matches benefit equally from the authority system regardless of which retrieval stream discovered them.