Bounded Authority Multiplier in ai-memory: How It Affects Retrieval Relevance

The bounded authority multiplier is a post-fusion scoring adjustment in ai-memory that re-weights search results based on canonical page metadata—such as kind, tier, pinned status, and explicit tags—to prioritize authoritative project knowledge over transient content.

The bounded authority multiplier is a core ranking mechanism in ai-memory (akitaonrails/ai-memory), an open-source knowledge retrieval system designed to surface trustworthy project documentation. It operates as a policy-driven boost that adjusts fused relevance scores after combining full-text, lexical, and vector similarity streams, ensuring that canonical rules and procedures rank higher than ephemeral notes.

How the Bounded Authority Multiplier Works

The retrieval pipeline in ai-memory fuses multiple relevance streams—including FTS5 full-text search, lexical-entity matches, link-neighbour RRF (Reciprocal Rank Fusion), and optional vector similarity—into a single candidate score. The bounded authority multiplier is applied after these streams are combined but before the final result truncation.

This multiplier re-weights each candidate page according to its canonical authority, derived from front-matter metadata. The effect is non-linear: high-authority pages move up in the result list (receiving a lower rank value), while low-authority pages are pushed down, even when raw semantic or text scores are comparable.

Authority Factors That Drive the Multiplier

Four primary metadata fields influence the bounded authority multiplier:

• Page kind – Pages categorized as rules, decisions, procedures, or gotchas receive higher authority boosts than narrative or transient content.
• Tier – The knowledge tier (working, episodic, semantic, procedural) determines base authority; procedural tiers outrank ephemeral working notes.
• pinned flag – Pinned pages receive the strongest authority multiplier and are exempt from temporal decay, ensuring persistent visibility.
• Explicit tags – Front-matter tags prefixed with + increase authority, while - tags decrease it, allowing fine-grained policy control.

Implementation in the ai-memory Source Code

The architecture specification in docs/ARCHITECTURE.md introduces the multiplier as a mechanism that "adjusts relevance using canonical page kind, tier, pinned, and explicit positive/negative front-matter tags" (lines 120–124).

The actual implementation resides in crates/ai-memory-store/src/lib.rs around line 6890, where the final rank calculation multiplies the fused score by the authority factor. The authority factor itself is computed in crates/ai-memory-store/src/reader.rs, which parses page metadata to derive the composite authority score used during the final ranking phase.

Impact on Search Result Ranking

The bounded authority multiplier ensures that trustworthy, policy-level knowledge surfaces first. When two pages have similar FTS5 or vector similarity scores, the one with higher canonical authority—such as a pinned procedural rule versus an episodic working note—will achieve a lower (better) rank value.

This design preserves the ability to retrieve less-authoritative content when needed, but prevents transient or test-level evidence from dominating results when canonical documentation exists.

Query Examples

When executing a memory_query, the returned results automatically incorporate the bounded authority multiplier.

use ai_memory_store::MemoryStore;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Initialise the store pointing at the default data directory
    let store = MemoryStore::open_default().await?;

    // Perform a query – results are re-ranked by the bounded authority multiplier
    let results = store
        .memory_query("how to reset a project")
        .await?
        .take(10);

    for page in results {
        println!(
            "Score: {:.3} – Title: {} – Authority: {}",
            page.rank,              // lower = more relevant after multiplier
            page.title,
            page.authority_factor,  // value contributed by the multiplier
        );
    }

    Ok(())
}

For command-line usage, the CLI applies the same backend logic:

# Returns top 10 results with authority-weighted ranking

$ ai-memory query "how to reset a project" --limit 10

In both cases, the rank field reflects the fused score after the bounded authority multiplier has been applied.

Summary

• The bounded authority multiplier is a post-fusion ranking adjustment in ai-memory that applies after combining FTS5, lexical, and vector streams.
• It re-weights results based on canonical authority metadata: page kind, tier, pinned status, and explicit +/- tags.
• Pinned pages receive the maximum authority boost and are immune to decay.
• The implementation spans docs/ARCHITECTURE.md (design), crates/ai-memory-store/src/lib.rs (application at line ~6890), and crates/ai-memory-store/src/reader.rs (calculation).
• This mechanism ensures authoritative project knowledge surfaces above transient content without sacrificing recall.

Frequently Asked Questions

When is the bounded authority multiplier applied during query execution?

The multiplier is applied after the fusion of relevance streams (FTS5, lexical-entity, link-neighbour RRF, and vector similarity) but before the final truncation of results. This intermediate stage allows the system to re-rank candidates based on policy-driven metadata before returning the top-k results to the user.

Which page metadata fields affect the authority multiplier?

Four fields determine the multiplier value: page kind (rule, decision, procedure, gotcha), tier (working, episodic, semantic, procedural), the pinned boolean flag, and explicit tags (+ for positive authority, - for negative). These are defined in page front-matter and parsed during indexing.

How does the pinned flag interact with the authority multiplier?

Pages marked with pinned: true receive the strongest authority multiplier available in the system. Additionally, pinned pages are exempt from temporal decay algorithms, meaning their authority remains constant over time, ensuring persistent high-ranking placement for critical project knowledge.

Where in the source code is the bounded authority multiplier implemented?

The design is documented in docs/ARCHITECTURE.md at lines 120–124. The application logic resides in crates/ai-memory-store/src/lib.rs around line 6890, where the fused rank is multiplied by the authority factor. The underlying calculation of the authority factor from metadata occurs in crates/ai-memory-store/src/reader.rs.

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