Vector Stores Overview

sovseal uses a hybrid, local-first vector database architecture. All read operations and search lookups occur entirely on your local disk to guarantee maximum performance and zero network dependency.

The Dual-Store Architecture

graph TD
    User([User Prompt]) --> Agent[AI Agent / IDE]
    Agent -->|1. recall_memory < 10ms| LocalDB[(LanceDB on Disk)]
    Agent -->|2. store_memory| LocalDB
    LocalDB -->|3. Write-Behind Queue| SyncWorker[Background Sync Worker]
    SyncWorker -->|4. Encrypted Snapshots| EdgeEndpoint[Supabase Edge Replication]
    EdgeEndpoint -->|5. Ciphertext Storage| RemoteDB[(Postgres + pgvector)]

1. Local Vector Store (LanceDB)

The primary datastore is a serverless LanceDB database initialized directly on your local device.

• LanceDB does not run as a background daemon; it is connected directly by the client process using the Arrow-backed binary format.
• Queries are executed in sub-10ms (6.1ms p50 warm recall) using flat or ANN indexing on Float32 normalized vectors.

2. Edge Replication (Postgres + pgvector)

When you configure an API Key and Endpoint, a background SyncWorker monitors your local LanceDB for rows with sync_status = 'pending'.

• The worker encrypts the data using client-side AES-256-GCM before uploading.
• The ciphertext is pushed to the edge snapshot endpoint (public.agent_state_snapshots in Supabase with pgvector).
• If you lose your local config or database, you can restore your entire memory sequence down to the latest sequence number.
• The remote server remains blind to the plaintext; it only manages hashes and encrypted snapshot payloads.