> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sovseal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LanceDB: sovseal's Local Vector Store

> The only vector store in sovseal — local, on-device LanceDB. Schema, file layout, thread safety, and what actually replicates to the server.

**LanceDB** is sovseal's local vector store — the only vector store in the system. All semantic search (`recall_memory` / `client.recall()`) runs against it, entirely on-device.

<Note>
  There is no remote or server-side vector store. The replication server never receives embeddings — only encrypted `text` and metadata. If you're looking for how remote data is stored, see [Storage Architecture](/self-hosted/bring-your-own-storage): it's two Postgres tables plus a ciphertext bucket, not a vector database.
</Note>

## How local search works

```mermaid theme={null}
graph TD
    User([User Prompt]) --> Agent[AI Agent / IDE]
    Agent -->|1. recall < 10ms| LocalDB[(LanceDB on Disk)]
    Agent -->|2. store| LocalDB
    LocalDB -->|3. Write-Behind Queue| SyncWorker[Background Sync Worker]
    SyncWorker -->|4. Encrypted Snapshots| EdgeEndpoint[Supabase Edge Replication]
```

LanceDB runs as an embedded serverless library inside your agent or MCP server process — no background daemon, no connection management. Queries execute in sub-10ms (6.1ms p50 warm recall) using vector search over Float32 normalized vectors.

## File System Layout

* **Default Database Location:** `~/.sovseal/db/`
* **Memories Table Path:** `~/.sovseal/db/memories.lance/`
* Override with the `SOVSEAL_DB_DIR` environment variable.

The table directories contain Arrow metadata files, schema configurations, and transaction logs. No background process is run.

## Arrow Table Schema (v2)

| Column               | Arrow Type                    | Purpose                                                                   |
| :------------------- | :---------------------------- | :------------------------------------------------------------------------ |
| **id**               | `Utf8` (non-nullable)         | Unique UUID generated client-side for each memory fact.                   |
| **vector**           | `FixedSizeList(384, Float32)` | The 384-dimensional ONNX normalized embedding vector.                     |
| **text**             | `Utf8` (non-nullable)         | The memory text (encrypted at rest under `k_rest`).                       |
| **timestamp**        | `Int64` (non-nullable)        | Epoch timestamp recording when the memory was stored.                     |
| **sync\_status**     | `Utf8` (non-nullable)         | Replication status: `"pending"` or `"synced"`.                            |
| **mem\_type**        | `Utf8` (non-nullable)         | `episodic` / `semantic` / `procedural` — sets the recall decay half-life. |
| **provenance**       | `Utf8` (non-nullable)         | `explicit` / `observed`.                                                  |
| **confidence**       | `Float32` (non-nullable)      | Confidence score at write time.                                           |
| **reinforce\_count** | `Int32` (non-nullable)        | Incremented on duplicate-content writes; boosts recall ranking.           |
| **last\_reinforced** | `Int64` (non-nullable)        | Epoch timestamp, drives temporal decay.                                   |
| **schema\_version**  | `Int8` (non-nullable)         | Row-level schema version, for the v1→v2 migration path.                   |
| **expires\_at**      | `Int64` (non-nullable)        | Retention/TTL epoch timestamp.                                            |

See [Memory Model](/platform/core-concepts/memory-model) for what these fields mean at the record-shape level, not just the storage level.

## Thread Safety & File Locking

* **Reader Isolation:** Multi-threaded read queries are non-blocking — multiple agents or editor panels can call `recall_memory` simultaneously.
* **Writer Coordination:** Writes are serialized via internal file-locking.
* **Transaction Log:** LanceDB uses append-only transaction logs. If your machine crashes mid-write, the database recovers to the latest consistent state on next start.

## Replication (what leaves the device)

When you configure an API key and endpoint, a background `SyncWorker` monitors local rows with `sync_status = 'pending'`, encrypts them client-side with AES-256-GCM, and pushes ciphertext to the edge endpoint — see [Replication & Sync](/platform/features/replication-sync) for the full batching, retry, and conflict-handling behavior. The vector column never replicates; only encrypted `text` and non-secret metadata do.