How Does Feather DB Work? Architecture Explained

Feather DB is an embedded vector database and context engine that runs as a single .feather file with no server dependency. It stores embedding vectors alongside metadata, retrieves them using HNSW approximate nearest-neighbor search accelerated by AVX2/AVX512 SIMD, and applies a five-layer context management system that adds time-aware decay, graph relationships, and adaptive scoring on top of the retrieval layer. The result: 0.19ms p50 ANN on 500K vectors, 97.2% recall@10, and a LongMemEval score of 0.693 with GPT-4o.

Layer 1: Adaptive Memory

Every stored memory in Feather DB carries three metadata fields that the adaptive scoring system uses:

• importance (0.0–1.0): Set at ingest time, updatable at runtime. Core facts like brand guidelines are set to 1.0 and never decay below retrieval threshold. Low-confidence experimental facts are set lower.
• recall_count: Auto-incremented every time the memory appears in a retrieval result. Never manually set.
• created_at: Timestamp set at ingest. Used by the decay formula.

The scoring formula:

stickiness    = 1 + log(1 + recall_count)
effective_age = age_in_days / stickiness
recency       = 0.5 ^ (effective_age / half_life_days)
final_score   = ((1 - time_weight) × cosine_similarity
                 + time_weight × recency) × importance

Parameters half_life and time_weight are set at query time, not at ingest — so the same database can serve different temporal profiles depending on the use case. A 7-day half-life for a real-time marketing system; a 90-day half-life for a long-running research agent.

Layer 2: Context Graph

Each stored node (memory) can link to other nodes via typed weighted edges. Nine built-in relationship types:

The context_chain API runs BFS traversal from a retrieved node up to a configurable hop depth, returning connected context that may not have been directly similar to the query vector. A retrieved preference can surface the session that set it, the task that prompted it, and the outcome that reinforced it — all in a single call.

Layer 3: Semantic Search

Feather DB uses HNSW (Hierarchical Navigable Small World) indexing for approximate nearest-neighbor search. HNSW builds a multi-layer proximity graph that supports greedy search from the top layer down to the base layer, finding approximate nearest neighbors in O(log n) time rather than O(n) for brute force.

Performance optimizations:

• AVX2/AVX512 SIMD: Distance computations (cosine, L2, inner product) use 256-bit or 512-bit vector instructions where the CPU supports them. This reduces distance computation time by 4–8× versus scalar operations.
• Hybrid search via RRF: BM25 keyword scores and dense vector similarity scores are combined using Reciprocal Rank Fusion. Queries that benefit from exact keyword matching (product codes, proper nouns, IDs) get better results than dense-only retrieval.
• In-process operation: No network hop. Memory access is a function call, not a database query. This produces the 0.19ms p50 latency at 500K vectors — compared to 1–10ms for networked vector databases.

Layer 4: Metadata Intelligence

Each stored memory carries a rich metadata object:

meta = fdb.Metadata(importance=0.9)
meta.set_attribute("user_id", "u_1234")
meta.set_attribute("session_id", "s_789")
meta.set_attribute("source", "conversation")
meta.set_attribute("confidence", "high")
meta.set_attribute("namespace", "brand_A")

Metadata enables filtered search — retrieve only memories where namespace = brand_A and user_id = u_1234 — without affecting index performance. Namespace isolation ensures multi-tenant deployments (multiple brands or users in one database) maintain hard retrieval boundaries.

Layer 5: Deploy Anywhere

Feather DB is embedded by design. The database lives in a single .feather file. There is no server process to manage, no network configuration, no infrastructure dependency.

Deployment options:

• Embedded library (current): pip install feather-db. Single file. Works in any Python process — Lambda functions, FastAPI servers, Jupyter notebooks, CLI scripts.
• Self-hosted Docker (current): Container with REST API for teams that want service-based access or language-agnostic clients.
• Feather Cloud (Q3 2026): Managed hosted option for teams that don't want to manage storage.

The MIT license means the embedded library can be used in commercial products without licensing costs or vendor dependency.

The full API in a minimal example

import feather_db as fdb

# Open or create database
db = fdb.DB.open("memory.feather", dim=768)

# Store a memory
meta = fdb.Metadata(importance=0.9)
meta.set_attribute("user_id", "u_1")
db.add(id="mem_001", vec=embed("User prefers TypeScript"), meta=meta)

# Link to related memory
db.link(from_id="mem_001", to_id="mem_000",
        rel_type="supersedes", weight=1.0)

# Retrieve with adaptive scoring
results = db.search(
    query_vec=embed("What language does the user prefer?"),
    k=10,
    half_life=30,
    time_weight=0.3
)

# Traverse context graph
chain = db.context_chain(query_vec, k=5, hops=2)

Benchmark results

FAQ

What file format does Feather DB use?

Feather DB stores everything in a single .feather file — the HNSW index, metadata, graph edges, and importance scores. There is no separate database server or configuration file.

What vector dimensions does Feather DB support?

Feather DB supports arbitrary vector dimensions set at database creation time via the dim parameter. Common choices are 768 (BERT/all-MiniLM), 1536 (OpenAI text-embedding-3-small), and 3072 (text-embedding-3-large).

How does Feather DB handle multi-tenant isolation?

Namespace isolation is handled via metadata filtering. Each memory is tagged with a namespace attribute; retrieval filters by namespace so User A's memories never appear in User B's results. No separate database file per tenant is required.

Does Feather DB support exact nearest-neighbor search?

Feather DB uses approximate nearest-neighbor search via HNSW (97.2% recall@10). Exact search (100% recall) can be run by scanning the full index, but this is O(n) and not recommended for production at scale. 97.2% recall is sufficient for virtually all AI memory use cases.

What license is Feather DB under?

Feather DB is MIT licensed. It can be embedded in commercial products without licensing fees or vendor lock-in to a managed service.