context_chain: How Feather DB Combines Vector Search with Graph Traversal for Richer AI Memory

Architecture Deep Dive · Feather DB v0.7.0 · April 2026

The Retrieval Gap

Standard RAG systems answer a simple question: what stored content is semantically similar to this query? They return the top-k nearest vectors. This is useful. It's also fundamentally limited.

Business knowledge isn't a collection of independent facts arranged by semantic proximity. It's a web of relationships. Causes and effects. Strategies and their executions. Hypotheses and their validations. Competitor moves and your responses to them.

When you retrieve a piece of context in isolation — divorced from what it connects to — you give the AI a fragment. It fills in the missing connections with general knowledge. Which means it fills them in incorrectly, for your specific situation.

The context_chain API in Feather DB is designed to solve this. It combines semantic vector search with typed graph traversal, returning not just the most relevant nodes, but the connected subgraph of your business knowledge that surrounds them.

Phase 1: Semantic Seeding

The first phase of context_chain is standard HNSW approximate nearest-neighbor search. You provide a query vector. The system returns the k most semantically similar nodes, scored by the adaptive decay formula:

final_score = ((1 - time_weight) × similarity + time_weight × recency) × importance

These k nodes are the seeds — the entry points into the context graph. They represent the direct semantic matches to your query.

chain = db.context_chain(
    query_vec,
    k=5,       # seed nodes from vector search
    hops=2,    # graph traversal depth
    modality="text"
)

Phase 2: Graph Expansion

The second phase traverses the typed relationship graph from each seed node. For each hop, Feather DB follows both outgoing edges (stored in Metadata.edges) and incoming edges (maintained in the incoming_index_ reverse map).

Each reached node is scored by a hop-discounted formula:

hop_score = (1 / (1 + hop)) × importance × stickiness

A node at hop=1 is scored at 50% of its importance-stickiness product. At hop=2, 33%. The graph expansion rewards proximity to the semantic seed while still surfacing connected context that wouldn't appear in a pure vector search.

Typed Edge Relationships

Edges in Feather DB are typed and weighted. Common relationship types in a business context engine:

same_ad — Connects image/video creatives to their text brief counterparts
contradicts — Connects competitor moves to the strategy positions they challenge
informed_by — Connects a creative to the research insight that shaped it
follows_up — Connects a campaign to the test it was derived from
targets — Connects a creative to the audience segment it was built for

# Building the relationship graph
db.link(from_id=competitor_creative_id, to_id=strategy_brief_id,
        rel_type="contradicts", weight=0.85)

db.link(from_id=image_creative_id, to_id=text_brief_id,
        rel_type="same_ad", weight=1.0)

db.link(from_id=campaign_v2_id, to_id=campaign_v1_id,
        rel_type="follows_up", weight=0.9)

What the Output Looks Like

A context_chain call returns a ContextChainResult containing all reached nodes with their hop distance, score, and metadata — plus the full list of traversed edges.

hop=0  ● [text/competitor_intel]  score=1.54
       Competitor launched 8.85% FD campaign post-Budget. Heavy Instagram video spend.

hop=0  ● [text/strategy_intel]  score=1.32
       Budget 2026 strategy: FD interest tax-free for seniors. Opportunity window: 6 weeks.

hop=1  └─ [text/strategy_intel]  score=0.45  [via: contradicts]
       RBI repo rate held 6.25%. Corporate bond yields attractive. Defensive FD positioning.

hop=1  └─ [video/ad_creative]  score=0.40  [via: same_ad]
       Video transcript for FD ad. Duration: 30s. Hook: "Ab aap apni savings ko..."

Notice what happened: the competitor creative surfaced the strategy brief not because of an explicit link between them, but because both were semantically proximate in the 768-dimensional embedding space. The graph traversal then extended that connection to the related video asset via a same_ad edge.

This is context that no pure vector search would produce. And it's exactly the kind of connected reasoning that AI agents need to make good decisions.

Performance Characteristics

Feather DB is designed for deployment in AI agent loops — environments where latency matters and infrastructure complexity is a liability.

Zero server overhead. The entire database, including the HNSW index, metadata, and edge graph, lives in a single .feather binary file. No network calls. No serialization overhead. Load and query directly in-process.
Sub-millisecond seed retrieval. HNSW approximate nearest-neighbor search at ef=200 over tens of thousands of nodes completes in under 1ms on standard hardware.
Linear graph expansion. BFS traversal over the edge graph is O(nodes + edges) in the traversed subgraph. For typical context chain queries with k=5 seeds and hops=2, this adds minimal overhead over the base vector search.

When to Use context_chain vs. search

Scenario	Use
Finding the most semantically similar documents to a query	`db.search()`
Finding all context connected to a topic — including multi-hop relationships	`db.context_chain()`
Giving an agent a rich, connected context window before a decision	`db.context_chain()`
Quick lookup of a specific entity by ID	`db.get(id)`
Streaming freshness-ranked context to a generation pipeline	`db.search()` with custom scoring config

The Compounding Value of a Rich Graph

The graph layer is where the Living Context Engine's value compounds over time. Every new piece of context you add and connect makes the traversal richer. Every edge you create opens new retrieval pathways. A context engine that's been running for six months, with well-maintained typed edges, returns qualitatively different results than one that's just started.

This is the compounding moat. Not the model. Not the prompts. The living, connected, intelligently-decayed context layer that your specific business has built over time.

Feather DB is the infrastructure that makes that possible without requiring a team of engineers to maintain it.

Feather DB v0.7.0 — github.com/feather-store/feather