Memory model and embeddings

Memory model and embeddings

memory stores durable facts for AI agents in a local SQLite database. Each memory is a short piece of text plus a 256-dimensional embedding vector, metadata, identity scopes, and an expiry. This page explains how the pieces fit together and how recall works.

What a memory is

A memory is a row in the SQLite database that contains:

Field	Purpose
id	UUID primary key.
agent_id	The agent or client that created the memory.
user_id	The user the memory is about.
content / fact	The text you want to remember.
embedding	256-dimensional vector generated from content.
metadata	Free-form JSON for tags, sources, or domains.
org_id	Fleet or organization scope.
workspace_id	Project or repository scope.
created_at / updated_at	Timestamps for ordering and sync.
expires_at	Optional TTL; NULL means forever.

The embedding is what makes semantic recall possible. Two pieces of text with similar meaning get vectors that are close together in 256-dimensional space, even if they use different words.

SQLite database

The default database lives at:

~/.memory/default.db

You can override it with --db or the MEMORY_DB_PATH environment variable. The binary creates the database, tables, and indexes automatically on first use.

memory keeps a write-ahead log (WAL) for concurrency. Call memory_vacuum to run a SQLite checkpoint and reclaim space after large deletions or imports.

Embedding model

memory bundles its own embedding runtime and model weights. On first recall or semantic search the binary extracts the runtime to a platform cache and loads the model. Subsequent calls are local and fast.

• Model output: 256-dimensional vectors.
• Similarity metric: cosine similarity (higher is closer).
• No external API call is made for embedding or recall.

The first semantic call may take a moment while the runtime initializes. After that, memory_recall and memory_search_semantic return results from the local store.

How recall works

memory_recall converts the query string into an embedding, then searches the database for the nearest neighbours by cosine similarity. Results include:

• the matching memory content,
• the metadata you stored,
• a similarity score.

Recall is scoped by the identity fields you provide. If you pass agent_id and user_id, memory searches within that slice. Adding workspace_id narrows it further. See Scopes and identity for how scoping changes what is returned.

Keyword vs semantic search

• memory_search is a keyword search over stored content. Use it when you know exact words.
• memory_search_semantic is a semantic search with optional metadata filters. Use it for meaning-based lookup.
• memory_recall is the high-level semantic search most agents call at the start of a task.

By default keyword search scores by term frequency. Set MEMORY_FTS5_BM25=1 to opt into FTS5 BM25 scoring instead. Optional feedback-aware re-ranking (opt in with MEMORY_FEEDBACK_RERANK) nudges recall and search results using the up/down feedback history stored with each memory.

Expiry and cleanup

Set ttl_ms when storing a memory to make it expire after a number of milliseconds. Expired memories are not returned by recall or search, but they remain in the database until you run memory_forget_expired or memory_prune.

Housekeeping tools are manual. Do not run them automatically unless you have a specific cleanup policy.

Privacy and sync

• Vectors and content stay in your SQLite file.
• Multi-device sync exchanges signed, encrypted delta logs. The relay only forwards opaque envelopes. See How sync works and Security model.

See also

• Scopes and identity
• How sync works
• Tools reference
• Prune old memories