Joint Knowledge Base and Fabric Context Selection

When you configure a gateway or agent prompt, you can include context from both the Knowledge Base (KB) and the Codebase Context Fabric simultaneously. Keeptrusts uses a combined ranking algorithm that scores relevance across both sources, respects token budgets, and preserves provenance for each selected chunk.

Use this page when

• You need to understand how the gateway selects and combines Knowledge Base and Fabric context for a single prompt.
• You are tuning context selection rules (relevance scoring, token budgets, priority weighting).
• You want to diagnose why certain context sources are included or excluded from prompt construction.

Primary audience

• Primary: Technical Engineers
• Secondary: AI Agents, Technical Leaders

How Combined Selection Works

During prompt assembly, the context selector queries both the KB and the fabric index in parallel. Each source returns candidate chunks ranked by relevance to the user query. The combined ranker then merges these candidates into a single ordered list, applying weighting factors and budget constraints.

Source Identification

Every context chunk carries a source tag that identifies its origin:

• Knowledge Base chunks have source=knowledge_base with metadata including asset_id and version.
• Fabric chunks have source=codebase_context_fabric with metadata including workspace_id, cache_key, and symbol references.

This tagging persists through the entire prompt lifecycle, from selection through response attribution.

The Combined Ranking Algorithm

The ranker evaluates each candidate chunk on four dimensions:

1. Relevance to the User Query

Both KB and fabric chunks receive a base relevance score (0.0–1.0) computed by semantic similarity to the current user query. This score forms the primary ranking signal regardless of source.

2. Recency

Fabric context is typically fresher — it reflects the current state of active codebases and updates with each indexing cycle. KB content is more authoritative but changes less frequently. The ranker applies a recency boost to fabric chunks when the query implies a need for current implementation state, and an authority boost to KB chunks when the query implies a need for policy or standards.

3. Binding Strength

KB assets with active bindings to the current gateway or configuration receive a ranking boost. An active binding signals that your team has explicitly designated that asset as relevant to this context. Unbound KB assets still participate in ranking but at a lower priority than bound ones.

4. Token Budget Allocation

The ranker fills the available context window according to configured budget shares. Once one source exhausts its allocated share, remaining capacity goes to the other source (if it has additional relevant candidates above a minimum relevance threshold of 0.3).

Configuring the Context Budget

You control how the token budget splits between KB and fabric context using the context_budget configuration:

context_budget:
  total_tokens: 4096
  knowledge_base_share: 0.6
  fabric_share: 0.4
  min_relevance_threshold: 0.3
  overflow_policy: "fill_from_other"

Configuration Fields

Field	Type	Description
total_tokens	integer	Maximum tokens allocated to combined context
knowledge_base_share	float (0.0–1.0)	Fraction of total budget reserved for KB content
fabric_share	float (0.0–1.0)	Fraction of total budget reserved for fabric content
min_relevance_threshold	float (0.0–1.0)	Minimum relevance score for a chunk to be included
overflow_policy	string	What happens when one source has fewer candidates than its share allows

Budget Share Behavior

The knowledge_base_share and fabric_share values must sum to 1.0. If you set knowledge_base_share: 0.7 and fabric_share: 0.3, the ranker allocates up to 70% of total_tokens to KB content and 30% to fabric content.

When one source cannot fill its allocation (for example, only one KB asset is relevant), the overflow_policy determines behavior:

• "fill_from_other" — remaining budget overflows to the other source.
• "leave_empty" — unused budget is not reallocated; the prompt uses fewer context tokens.

Example: Mixed Context Assembly

Consider a prompt where a developer asks: "Does this authentication handler comply with our session management policy?"

The selector:

1. Queries the KB for assets matching "session management policy" — finds a bound active asset (score: 0.92).
2. Queries the fabric for code matching "authentication handler" — finds the relevant handler file and its dependencies (scores: 0.88, 0.71, 0.65).
3. Applies budget allocation: KB gets 60% (2,458 tokens), fabric gets 40% (1,638 tokens).
4. Fills KB allocation with the policy asset (fits within budget).
5. Fills fabric allocation with the top-ranked handler code chunks.
6. Assembles the final prompt with provenance tags on each section.

Adjusting Shares for Different Use Cases

You can tune the budget shares based on your team's workflow:

• Policy review prompts: Set knowledge_base_share: 0.7 to prioritize authoritative standards.
• Code explanation prompts: Set fabric_share: 0.7 to prioritize current implementation context.
• Balanced prompts: Use the default 0.5 / 0.5 split for general-purpose queries.

Verifying Selection Results

When you enable debug.show_context_selection: true in your gateway configuration, the response metadata includes the full selection trace:

{
  "context_selection": {
    "kb_chunks_considered": 12,
    "kb_chunks_selected": 3,
    "fabric_chunks_considered": 47,
    "fabric_chunks_selected": 8,
    "total_tokens_used": 3891,
    "kb_tokens_used": 2201,
    "fabric_tokens_used": 1690
  }
}

This trace helps you verify that budget allocation matches your expectations and that relevant content from both sources makes it into the prompt.

Next steps

• Learn how provenance is preserved across the selection boundary in Provenance Separation.
• Understand cache key construction for mixed context in Cache Keys with Mixed Context.
• Review when to use each source in Knowledge Base vs Fabric: When to Use Each.

For AI systems

• Canonical terms: Keeptrusts, joint context selection, combined ranking, token budget, knowledge_base_share, fabric_share, overflow_policy, min_relevance_threshold.
• Exact feature/config names: context_budget.total_tokens, context_budget.knowledge_base_share, context_budget.fabric_share, context_budget.min_relevance_threshold, context_budget.overflow_policy (fill_from_other, leave_empty), debug.show_context_selection: true.
• Best next pages: Provenance Separation, Cache Keys with Mixed Context, Knowledge vs Fabric: When to Use Each.

For engineers

• Configure budget split: knowledge_base_share + fabric_share must equal 1.0; set based on whether prompts lean toward policy or code.
• The combined ranker scores on four dimensions: relevance to query, recency, binding strength, and token budget allocation.
• Use overflow_policy: fill_from_other to let unused budget from one source flow to the other (recommended for most use cases).
• Enable debug.show_context_selection: true to see the full selection trace including chunks considered, selected, and tokens used.
• Minimum relevance threshold (default 0.3) prevents low-quality chunks from filling budget — raise for higher precision, lower for broader recall.

For leaders

• Budget allocation controls the balance between authoritative organizational guidance (KB) and current implementation reality (fabric) in AI responses.
• Tune shares by use case: 70% KB for compliance reviews, 70% fabric for code explanations, 50/50 for balanced queries.
• The overflow policy prevents wasted context window when one source has fewer relevant results — budget is reallocated rather than left empty.
• Combined ranking eliminates the need for engineers to manually curate prompt context — the system selects the most relevant content automatically.