# Feather DB — Complete Documentation

> Feather DB is a lightweight, embedded vector database + living context engine. Zero-server, file-based, powered by a C++ core with Python bindings and a Rust CLI. Current version: v0.8.0.

---

## Overview

Feather DB is an embedded vector database designed for AI engineers building LLM applications. It requires no server, no Docker, and no network infrastructure. All data is persisted to a single `.feather` binary file that can be read with zero-copy SIMD operations.

**Core Features in v0.8.0:**

- **Multimodal Pockets** — A single entity ID can hold `text`, `visual`, and `audio` vectors in separate scoped HNSW indexes within the same flat file.
- **Context Graph & Chain** — Store directional relationships between entities natively. The `context_chain()` method combines ANN search with N-hop BFS graph traversal in a single call.
- **Adaptive Decay (Living Context)** — Vectors decay in relevance over time using a configurable half-life. This solves context overload in long-running RAG agents.
- **Rust CLI Tooling** — A dependency-free `feather-db-cli` binary for database inspection, debugging, and CI/CD pipelines.

---

## Installation

### Python Client

```bash
pip install feather-db
```

**Requirements:**
- Python 3.8+
- NumPy 1.22+

### Rust CLI

```bash
cargo install feather-db-cli
```

**Build from Source:**
```bash
git clone https://github.com/feather-store/feather.git
cd feather/cli
cargo build --release
```

---

## Quick Start

### Step 1: Create a Database

```python
from feather import DB

# Create a database for 384-dimensional vectors
db = DB.open("embeddings.feather", dim=384)
```

### Step 2: Add Multimodal Vectors

```python
import numpy as np

vectors = [np.random.rand(384).astype(np.float32) for _ in range(10)]

for i, vector in enumerate(vectors):
    # Add with an explicit modality string
    db.add(id=i, vec=vector, modality="text")

print(f"Added {len(vectors)} text vectors")
```

You can add multiple modalities to the same entity ID:

```python
db.add(id=42, vec=text_vec, modality="text")
db.add(id=42, vec=img_vec, modality="visual")
```

### Step 3: Search with Modality Namespaces

```python
query = np.random.rand(384).astype(np.float32)

# Search specifically within the "text" modality pockets
results = db.search(query, k=5, modality="text")

for vector_id, distance in results:
    print(f"ID: {vector_id}, Distance: {distance:.4f}")
```

### Step 4: Save and Persist

```python
# Flush index and data to disk
db.save()

# Load exactly the same way later:
# db = DB.open("embeddings.feather", dim=384)
```

---

## API Reference

### `DB.open(filename, dim)`

Initializes a new or existing Feather database using the flat binary format.

```python
db = DB.open("vectors.feather", dim=384)
```

**Parameters:**
- `filename` — Path to the `.feather` file
- `dim` — Vector dimension (globally scoped in v0.8.0)

---

### `db.add(id, vector, modality="text", metadata=None)`

Injects a vector under a specific entity ID. The `modality` parameter places this vector into a scoped HNSW index.

```python
db.add(1, vector, modality="visual", metadata={"label": "example"})
```

**Parameters:**
- `id` — Entity ID (integer)
- `vector` — NumPy float32 array of length `dim`
- `modality` — (v0.8.0) Multi-modal index target: `"text"`, `"visual"`, `"audio"`
- `metadata` — Optional JSON-compatible dict

---

### `db.search(query, k=10, filter=None, time_weight=False)`

Standard approximate nearest neighbor (ANN) search using HNSW.

```python
results = db.search(query, k=5, time_weight=True)
```

**Parameters:**
- `query` — NumPy float32 query vector
- `k` — Number of results to return
- `filter` — Optional metadata filter dict
- `time_weight` — If True, applies Adaptive Decay scoring (scores decay based on vector age and configured half-life)

**Returns:** List of `(id, distance)` tuples sorted by closest distance.

---

### `db.context_chain(query, k=5, hops=2, modality="text")` *(NEW in v0.8.0)*

Performs a semantic vector search, followed instantly by a configured N-hop BFS expansion across the Context Graph.

```python
res = db.context_chain(
    query=vec_q,
    k=5,    # seed search
    hops=2, # BFS expansion
    modality="text"
)
```

**Parameters:**
- `query` — NumPy float32 query vector
- `k` — Number of seed ANN results before graph expansion
- `hops` — BFS depth across tracked entity edges
- `modality` — The vector space to seed the graph expansion from

**Returns:** Expanded list of entity IDs reachable within `hops` from the top-k ANN results.

---

### `db.save()`

Flushes the current in-memory index and all vector data to disk atomically.

---

### `db.link(id_a, id_b)`

Creates a directed edge in the Context Graph between two entity IDs. Used to pre-wire relationships for use with `context_chain()`.

```python
db.link(42, 99)  # Entity 42 "knows about" entity 99
```

---

## Storage Format

Feather uses a highly optimized `.feather` binary blob to persist vectors and graph edges directly to disk without a running server process.

### v0.8.0 Binary Layout

| Offset | Field | Value |
|--------|-------|-------|
| `0x00` | Magic Number | `0x46454154` ("FEAT") |
| `0x04` | Version Block | v0.8.0 header size |
| `0x08` | Global Dim Size | e.g. 384 or 768 (Int32) |
| `0x12..` | Records / HNSW Edge Block | Node ID + Vector Data + Context Graph Edges |

Every `.feather` file enforces a strict binary protocol that ensures:
- Safety guarantees on read/write
- Zero-copy reads via SIMD (AVX-2/NEON) on supporting architectures
- Efficient BFS graph adjacency encoding for the Context Graph

---

## Integrations

### LangChain

Feather DB can be used as a custom `VectorStore` in LangChain by wrapping the `db.add()` and `db.search()` methods. The `modality` parameter maps cleanly to LangChain namespaces.

### LlamaIndex

Use Feather as a custom vector store backend in LlamaIndex. Implement the `VectorStore` interface using `db.add()` for ingestion and `db.search()` for retrieval.

### Custom Embedding Pipelines

Feather is embedding-model agnostic. Any model producing a fixed-dimension float32 NumPy array (sentence-transformers, OpenAI `text-embedding-3-small`, Cohere, etc.) works out of the box. Just ensure `dim` matches the model's output dimension.

---

*Source: https://getfeather.store/docs | Version: 0.7.0 | Last updated: March 2026*