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

# Memory Vault Internals

> Deep dive into the AES-GCM and libSQL architecture.

## 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.