Docs
Storage and embeddings
Cloud, local and hybrid storage, the on-device embedding model, and what changes when you bring your own provider.
Where your data is stored and where embeddings are made are two separate choices. Both are set in the app.
Storage modes
| Mode | Where data lives | Network |
|---|---|---|
| Cloud (default) | Your account, with raw sessions as encrypted objects | Uses the Agent Memory API |
| Local | SQLite and sqlite-vec on this computer | Outbound traffic blocked |
| Hybrid | Both at once | Uses the Agent Memory API |
Local mode
Local mode is a storage choice and a lock. While it is on, Agent Memory blocks its own outbound traffic. If the setting can't be read, it stays blocked instead of falling back to the cloud, and environment variables can't lift it.
Switching to local removes the saved cloud sign-in and external provider keys, and resets the embedding provider to the local model.
Cloud mode
Raw sessions are compressed, encrypted with authentication and stored as objects. The database keeps indexes, vectors and retrieval metadata, and enforces ownership at the PostgreSQL boundary. You can restore a session to its original JSONL:
agent-memory cloud sources --limit 100
agent-memory cloud restore --source-id <source-id> --revision <revision> --output restored-session.jsonlRestore checks every chunk and the whole file against SHA-256. If the source changes while you restore, it fails instead of writing a partial file.
Embeddings
Agent Memory turns text into 1024-dimensional vectors with BGE-M3.
| Provider | Runs on | Storage modes |
|---|---|---|
| Local (default) | Mac: MLX on Apple Silicon. Windows: onnxruntime on the CPU. | All |
| DeepInfra | DeepInfra, with your API key | Cloud and hybrid |
| Gemini | Google Gemini, with your API key | Cloud and hybrid |
The local model
The model isn't bundled with the app. It downloads from Hugging Face into the app's own cache the first time it's needed. Start the download from Settings, or run:
agent-memory model prepareEmbeddings for your sessions are made on your device, never on Agent Memory's servers. In cloud mode the app picks up pending embedding jobs and sends the vectors back.
Your own provider
If you choose DeepInfra or Gemini, the text being embedded, which includes session text and search queries, is sent to that provider. Keys are kept in the macOS Keychain or the Windows Credential Manager. Agent Memory has no shared key.
When vectors aren't available
If the model, the vector index or the embedding process isn't available, search uses words alone. It doesn't reach out to the network to make up for it.