Crux Store

import { inMemoryCruxStore, keySpace, matchesFilter } from '@crux/core/store'
import type {
  CruxStore, JsonObject, StoreEntry, ListOptions, ListResult,
  ScoredEntry, SparseVector, VectorSearchOptions, VectorSearchQuery, StoreEvent, StoreSetEvent, StoreDeleteEvent,
  EmbedFn, ToolConfig,
} from '@crux/core/store'

Overview

Use @crux/core/storage for new application code. It exposes the canonical DataStore, VectorStore, and BlobStore interfaces.

@crux/core/store remains the low-level module for store utilities such as keySpace, filtering helpers, and existing adapter compatibility exports.

CruxStore Interface

set(key, value, options?)

The optional options parameter accepts:

list(prefix, options?)

Results are sorted by value.updatedAt descending (newest first). Supports pagination and filtering.

vectorSearch(embedding, options?)

Reads value.embedding (a number[]) from stored entries and ranks by cosine similarity. Returns empty if no entries have embeddings. Optional -- stores without vector capabilities can omit this.

searchVectors(query)

Use searchVectors() when your store supports sparse-only or hybrid retrieval.

type SparseVector = {
  indices: number[]
  values: number[]
}

type VectorSearchQuery = {
  dense?: number[]
  sparse?: SparseVector
  fusion?: 'rrf' | 'dbsf'
  limit?: number
  threshold?: number
  filter?: Record<string, unknown>
}

Rules:

• dense-only stores may implement only vectorSearch()
• sparse-only queries require searchVectors({ sparse })
• hybrid queries require searchVectors({ dense, sparse })
• unsupported query modes should throw explicitly rather than silently degrading

subscribe(callback)

Returns an unsubscribe function. Events are discriminated unions -- narrow on event.type to access value (only present on 'set').

inMemoryCruxStore()

Create an in-memory CruxStore backed by a Map. All data lives in process memory and is lost on restart. Supports vectorSearch() (linear scan), subscribe() (synchronous notifications), and supportsTtl().

Use for: test suites, local development, rapid prototyping. Not for production.

import { inMemoryCruxStore } from '@crux/core/store'

const store = inMemoryCruxStore()
await store.set('plan:abc', { title: 'My Plan', version: 1, updatedAt: Date.now() })
const plan = await store.get('plan:abc')

keySpace

Centralized store key namespace registry. All CruxStore key patterns in one place. Modules import key builders from here instead of scattering string literals.

Each namespace provides:

• key(...) -- build a full key from identifiers
• prefix -- the constant prefix for list/scan operations

import { keySpace } from '@crux/core/store'

// Build a key
const key = keySpace.plan.key('abc')         // 'plan:abc'
const key = keySpace.flow.key('flow-123')    // 'crux:flow:flow-123'

// Use prefix for listing
const result = await store.list(keySpace.plan.prefix)  // 'plan:'

Registered Namespaces

ListOptions

ListResult

StoreEntry

ScoredEntry

Extends StoreEntry with a similarity score from vector search.

VectorSearchOptions

VectorSearchQuery

StoreEvent

Discriminated union of store change events. Narrow on event.type.

store.subscribe?.((event) => {
  if (event.type === 'set') {
    console.log('Updated:', event.key, event.value)
  } else {
    console.log('Deleted:', event.key)
  }
})

JsonObject

type JsonObject = Record<string, unknown>

All store values are this shape -- a JSON-serializable object.

Implementations

Types

import type {
  CruxStore, JsonObject, StoreEntry,
  ListOptions, ListResult,
  ScoredEntry, VectorSearchOptions,
  StoreEvent, StoreSetEvent, StoreDeleteEvent,
  EmbedFn, ToolConfig,
} from '@crux/core/store'

Related

• Guide: CruxStore
• Guide: Memory stores
• Reference: Memory
• Reference: Convex
• Reference: Upstash