What Is a Context Chain? How Feather DB Connects Memory

A context chain in Feather DB is the result of running a combined vector search and graph traversal: the search finds the most semantically relevant memories for a query, and the graph traversal follows typed edges from those seed memories to surface connected context — supporting evidence, superseded versions, same-session facts — that wouldn't be directly retrieved by similarity search alone. The result is a structured chain of memories that gives an AI agent the full context around a retrieved fact, not just the fact itself.

Why isolated retrieval is not enough

Semantic similarity retrieval returns the memories most similar to a query vector. For many queries, this is sufficient. For agent reasoning that requires understanding the context around a fact, isolated retrieval leaves critical information on the table.

Example: A coding assistant agent retrieves the memory "User prefers TypeScript for all new modules" in response to a query about adding a feature. Useful — but incomplete. The full context includes: when this preference was established (three months ago, after migrating the auth module), why it supersedes the older preference ("User was using JavaScript, preferred callbacks"), and what project it applies to (main repo, not the legacy Python microservice). Without context chain traversal, the agent retrieves a fact. With it, the agent retrieves a fact plus its history and supporting context.

How context chains work in Feather DB

The context_chain API runs a two-phase operation:

Phase 1: Seed retrieval. Standard adaptive vector search returns the top-k most relevant memories, ranked by the combined score (cosine similarity, recency, importance). These seed nodes are the starting points for graph traversal.

Phase 2: BFS traversal. From each seed node, breadth-first search follows typed edges up to a configurable hop depth. At each hop, the traversed nodes are added to the result set with their edge type and weight. The traversal respects namespace boundaries — only edges within the querying namespace are followed.

The combined result is a chain: the seed memories (direct matches) plus the connected context (graph traversal) structured by relationship type.

API example

import feather_db as fdb

db = fdb.DB.open("agent.feather", dim=768)

# Store memories with relationships
db.add("pref_ts", vec=embed("User prefers TypeScript for new modules"),
       meta=fdb.Metadata(importance=0.9))
db.add("pref_js", vec=embed("User was using JavaScript with callbacks"),
       meta=fdb.Metadata(importance=0.3))
db.add("migration_note", vec=embed("Auth module migrated to TypeScript in March"),
       meta=fdb.Metadata(importance=0.7))

# Link memories
db.link("pref_ts", "pref_js", rel_type="supersedes", weight=1.0)
db.link("pref_ts", "migration_note", rel_type="caused_by", weight=0.8)

# Retrieve context chain
chain = db.context_chain(
    query_vec=embed("what language should I use for the new feature?"),
    k=3,      # top-3 seed nodes
    hops=2    # follow edges up to 2 hops
)

# chain contains:
# - pref_ts (direct match, seed)
# - pref_js (1 hop via supersedes edge from pref_ts)
# - migration_note (1 hop via caused_by edge from pref_ts)

Context chain structure

Each node in a context chain result carries:

Context chains vs flat retrieval

When to use context chains

Use the context_chain API when:

• The agent's reasoning benefits from understanding why a fact is true, not just that it's true
• Facts may have been updated or superseded and the agent needs to know the history
• Session context matters — facts from the same conversation should be considered together
• Supporting evidence for a decision should be surfaced alongside the decision itself

Use plain search when:

• The task is simple fact lookup — retrieve the most relevant isolated memories
• Graph context is not relevant to the query
• Latency is critical and even sub-millisecond BFS overhead matters

Context chains in performance marketing (Hawky.ai)

Hawky.ai uses context chains to retrieve creative intelligence for brief generation. A query for "bottom-funnel urgency creative for female 35–44 audience" retrieves the best-performing creative as a seed, then follows graph edges to surface: the performance data that validated it (supports edge), the brand guideline that informed it (derived_from edge), and the superseded variants that performed worse (supersedes edges). The creative AI receives the full chain — not just the top headline, but the context that explains what worked and what didn't.

FAQ

What is a context chain in Feather DB?

A context chain is the result of combining vector search (finding the most relevant seed memories) with BFS graph traversal (following typed edges to surface connected context). It returns a structured set of memories organized by their relationship to the retrieved seed nodes.

How many hops should a context chain traverse?

For most agent memory use cases, 2 hops is sufficient — it surfaces direct matches plus one level of connected context (supporting evidence, superseded versions, session facts). At 3 hops, chains can grow large with loosely-related context. Start at 2 and increase only if chains are consistently too shallow for your use case.

Does context chain traversal slow down retrieval?

BFS traversal adds sub-millisecond overhead to the base 0.19ms seed retrieval time for typical agent memory graphs (thousands of nodes). For large graphs (100K+ nodes) with many edges per node, limit hop depth to control traversal cost. The overhead is negligible relative to LLM inference time.

Can context chains cross namespace boundaries?

No. BFS traversal respects namespace boundaries — edges are only followed within the querying namespace. This ensures that in multi-tenant deployments, User A's context chain cannot surface User B's connected memories.

How does a context chain handle superseded memories?

When a new memory supersedes an older one via a supersedes edge, the chain traversal surfaces both — the new memory as a seed node and the old memory as a 1-hop traversal result labeled with the supersedes edge type. The agent can see both the current state and the history, enabling it to understand what changed and when.