Skip to main content

Storage API Reference

The storage crate provides the memory persistence layer for Soul Kernel.

Overview

The storage system implements a hybrid approach combining SQLite for reliable persistence and vector storage for semantic search capabilities.

Core Types

MemoryEvent

The fundamental unit of memory storage.
Fields:
  • id - Unique identifier (UUID v4)
  • timestamp - UTC timestamp of event creation
  • author - Device or source identifier
  • event_type - Type of memory event
  • content - Human-readable content
  • embedding - Vector representation for similarity search
  • metadata - Additional JSON metadata

MemoryEventType

MemoryQuery

Parameters for vector similarity search.
Fields:
  • embedding - Query vector for similarity search
  • top_k - Maximum number of results to return
  • score_threshold - Minimum similarity score (0.0 to 1.0)
  • filter - Optional filters to apply

MemoryFilter

Traits

MemoryStore

The core trait that all storage implementations must provide.

Implementations

HybridMemoryStore

The recommended implementation combining SQLite and vector search.

SqliteMemoryStore

Direct SQLite implementation for simple use cases.

Error Handling

StorageError

Usage Examples

Basic Usage

Synchronization

Performance Characteristics

Best Practices

  1. Batch Inserts: Use transactions for bulk operations
  2. Embedding Size: Keep embeddings reasonable (384 dims recommended)
  3. Indexing: Add custom indexes for frequent query patterns
  4. Compaction: Run compact() during maintenance windows
  5. Error Handling: Always handle StorageError appropriately

Thread Safety

All storage implementations are thread-safe and can be shared across async tasks using Arc.

Migration Support

The storage layer includes automatic schema migrations:
Current schema version: 1

Configuration

SQLite Settings

The SQLite adapter uses these optimizations:
  • WAL mode for better concurrency
  • Normal synchronous mode
  • 64MB cache size
  • In-memory temp store

Vector Store Settings

When using Qdrant (currently mocked):
  • HNSW index with M=16, ef=64
  • Cosine similarity metric
  • Automatic collection creation

See Also

Change Log

  • 2025-06-13: Initial API documentation created