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

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 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 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 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 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 (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, the authority adjustment occurs after fusion:

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

The Authority::adjust_rank implementation transforms scores as follows:

// 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 (lines 5692-5696) confirms the arithmetic relationship:

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

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

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

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

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 — Describes "bounded authority multiplier adjusts relevance using canonical" (line 117)
• 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 — Authority extraction, candidate window limits, and rank adjustment (lines 190-211, 404-409)
• 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 — 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. 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.

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