Skip to main content

​
Architecture Overview

The Encrypted Memory Vault is a local-first, vectorized storage engine built on top of Turso (libSQL) and the macOS Keychain. It provides standard CRUD operations for the AgentRuntime while guaranteeing that sensitive developer context is never written to disk in plaintext. The memory vault lives in src-tauri/src/services/memory_vault/ and interfaces primarily with the EmbedderService and AgentMemory wrapper.

​
Core Components and Functions

​
crypto.rs

This module handles the low-level AES-256-GCM encryption mechanics.
  • encrypt(data: &[u8], key: &[u8]) -> Result<Vec<u8>, String> Generates a random 12-byte nonce, encrypts the plaintext data using the provided 32-byte key, and returns the concatenated nonce + ciphertext.
  • decrypt(encrypted_data: &[u8], key: &[u8]) -> Result<Vec<u8>, String> Extracts the 12-byte nonce from the beginning of the encrypted_data, and decrypts the remaining ciphertext using the AES-256-GCM algorithm and the symmetric key.

​
key_provider.rs

This module defines the VaultKeyProvider trait, which abstracts the retrieval of the master encryption key.
  • MacOSKeychainVaultKeyProvider::get_or_create_master_key() Interfaces with the security-framework crate to fetch the 32-byte master key from the macOS Keychain. If the key does not exist or raises an ItemNotFound error, it securely generates a new 32-byte key using ring::rand, encodes it in Base64, and stores it in the Keychain.

​
service.rs (MemoryVaultService)

This is the primary repository layer for memory management. It initializes the libSQL connection pool and applies the AES-256-GCM encryption before any data touches the database.
  • new(app_data_dir: PathBuf) -> Result<Self, String> Initializes the native macOS Keychain provider and establishes the database connection to rainy_cowork_v2.db. It runs schema migrations to ensure the memories table exists with FLOAT32 vector columns.
  • store(&self, input: StoreMemoryInput) -> Result<String, String> Takes a StoreMemoryInput struct containing the plaintext content, source, vector (generated by EmbedderService), and sensitivity. It encrypts the plaintext content using the provider’s master key and inserts the Base64-encoded ciphertext and vector into the database.
  • retrieve(&self, query_vector: &[f32], limit: usize) -> Result<Vec<MemoryEntry>, String> Performs a native vector_distance_cos cosine similarity search against the stored libSQL vectors. For the closest matches, it fetches the Base64-encoded ciphertext, decodes it, and decrypts it back into plaintext, returning fully hydrated MemoryEntry objects.
  • delete(&self, id: &str) -> Result<(), String> Standard deletion of a memory by its UUID.
  • clear(&self) -> Result<(), String> Truncates the memories table entirely.

​
Extensibility

The vault is currently hardcoded to use MacOSKeychainVaultKeyProvider. For cross-platform support (Windows/Linux), new implementations of the VaultKeyProvider trait must be created utilizing keyring-rs or equivalent secure enclaves.