# ADR-007: Personal Memory — sqlite-vec + SQLCipher

**Status:** Accepted  
**Date:** 2026-05-18  
**Deciders:** Mohsen Seyedkazemi Ardebili

---

## Context

The personal-memory layer is the foundation for the agent loop's recall capability and v2 RAG-augmented reasoning. Three trade-offs drive the decision: embedded vs. server-based vector store; encryption-at-rest scheme; and which embedding model to bundle. An unencrypted, vendor-controlled personal memory store is a privacy and security failure — the Microsoft Recall 2024 launch is the public example of this failure mode. YazSes' commitment is the opposite: user-controlled, encrypted at rest, fully local.

sqlite-vec is the canonical embedded vector store in 2026: pure C, no external dependencies, KNN and ANN, runs on every platform where SQLite runs. SQLCipher provides AES-256 encryption at rest with a user-derived key. Spike S-4 (2026-05-18) confirmed that sqlite-vec and SQLCipher coexist without issue when compiled with `SQLITE_CORE` and `PRAGMA cache_size` tuned appropriately.

## Decision

The personal-memory store is SQLite + sqlite-vec + SQLCipher, with a bundled BGE-small-en embedding model (384-dimensional; all-MiniLM-L6-v2 as fallback) for query and commit embeddings.

Key implementation details:

- Encrypted database at `~/.local/share/yazses/memory.db`.
- Encryption key: PBKDF2-derived (default 256k iterations) from a user passphrase + a machine-bound salt at `~/.local/share/yazses/.salt`, protected by OS file ACLs.
- Passphrase ceremony: first `commit_to_memory` invocation triggers `yazses memory init`, which prompts for a passphrase; the derived key is held in daemon RAM for the session lifetime.
- Schema: a `vec0` virtual table with columns for embedding (float[384]), transcript, source, EditorContext JSON blob, tags, creation timestamp, and TTL.
- TTL enforcement: an in-process sweeper deletes expired records on a configurable cadence (default once per hour).
- `forget_last(minutes)` is both a typed LLM tool and a CLI command (`yazses memory forget --last 30m`).
- `PRAGMA cache_size = -200000` (200 MB) is required for acceptable KNN query performance at 100k records. Without this setting SQLCipher re-decrypts embedding pages on every query; with it, P50 query latency is 4 ms vs 40 ms at 10k records.

## Consequences

**Positive:**
- Single-file encrypted storage on every platform SQLite supports.
- Fully auditable via standard SQL tooling once unlocked — transparent to the user.
- Open-source dependency chain: sqlite-vec (Apache-2.0), SQLCipher (BSD-3-Clause).
- ANN index paths (IVF, DiskANN) are available for scale beyond the brute-force regime (~100k records).
- The schema is open and documented; community plugins for personal memory analytics are straightforward.

**Negative / trade-offs:**
- Passphrase loss equals data loss. There is no recovery path by design — any recovery mechanism is a privacy backdoor.
- BGE-small adds approximately 80 MB to the install footprint.
- SQLCipher is open-source but maintained by a commercial entity (Zetetic); `sqleet` exists as an alternative fallback if the licence situation evolves unfavourably.

## Implementation

The `PersonalMemory` module is in `yazses-memory/src/`. SQLite FFI uses `rusqlite` with the `sqlcipher` feature. sqlite-vec is loaded as a runtime extension. The embedding model runs via `ort` (ONNX Runtime) in `yazses-memory/src/embedder.rs`. Memory CLI commands are wired through the IPC layer (see ADR-010).