Memory
Memory makes conversations compound: a fact, preference, or decision Lucy picks up in one chat is recalled in the next. It is off by default and you stay in control - review, add, or wipe anything at any time.
Two stores work together:
- Profile - a small, always-on block of stable identity ("who you are": name, role, company, communication style). It's injected into every reply.
- Collection - a searchable set of individual memories. Only the ones relevant to your current message are pulled in.
When a reply draws on the collection, a "🧠 Lucy used N memories" note appears under it.
Two modes
| Connected mode (signed in, Supabase) | Standalone (desktop app) | |
|---|---|---|
| Storage | Postgres (lucy.memories), RLS-isolated per user | Your browser's IndexedDB |
| Recall | Hybrid: embeddings + full-text, fused | Keyword (lexical) only |
| Enable | Admin toggles Settings → Memory | You toggle the local switch |
| Embedder | Admin-configured (cloud or local) | Not used |
Everything below applies to both modes except where it says connected mode only.
Three kinds of memory
Each memory is typed, which changes how fast it fades and how it's labelled when injected:
| Type | What it holds | Half-life | Injected as |
|---|---|---|---|
| Semantic | Stable facts & preferences ("prefers Tailwind") | 60 days | Facts |
| Pragmatic | Working style / current intent | 10 days | Working style |
| Episodic | What happened, and when ("Q3 launch moved to October") | 30 days | Recently |
Importance decays exponentially toward each half-life, so transient intent ages out quickly while durable facts persist.
How recall works (connected mode)
When you send a message, Lucy retrieves the best memories and injects them into its context. Retrieval is hybrid:
- Vector search - your message is embedded and compared against memory
embeddings by cosine distance (pgvector /
halfvec, HNSW index). - Full-text search - the same message runs as a Postgres
websearch_to_tsqueryagainst a generatedtsvectorcolumn. - Reciprocal Rank Fusion - the two ranked lists are merged with RRF
(
1 / (k + rank), k = 60), so a memory that scores well on either signal surfaces. This is robust when one signal is weak (e.g. a query that shares no words but the same meaning). - Final ranking - fused candidates are re-scored by
relevance × importance × recency, nudged up slightly each time a memory is actually used (reinforcement).
Retrieved memories are "touched" - their access count and last-used timestamp bump - so frequently-useful memories rank higher over time.
In standalone mode there's no embedder or Postgres: recall is keyword overlap over your local memories, scored by the same importance × recency curve.
Entity salience
As Lucy extracts memory it also tracks entities - client names, products, people, recurring terms. Each time an entity reappears its occurrence count goes up, and memories mentioning a high-salience entity get an importance bonus. A client you talk about constantly naturally outranks a one-off mention.
How saving works - end-of-conversation reconciliation
After a turn completes, an extraction pass (fire-and-forget, using your chat model) reads the conversation and proposes durable memories. Crucially, it doesn't just append - it reconciles each candidate against what Lucy already knows and tags it with an operation:
| Op | Meaning |
|---|---|
| ADD | Genuinely new - insert it |
| UPDATE | Replaces an existing memory (a fact changed) |
| MERGE | Folds into an existing memory |
| SKIP | Redundant or trivial - store nothing |
This keeps the collection from filling with near-duplicates. The extractor is deliberately conservative: it prefers storing nothing over noise.
When an UPDATE/MERGE contradicts an existing memory, the contradiction policy (admin setting) decides what happens:
- Supersede (default) - overwrite in place; only the current truth is kept.
- Keep history - mark the old version invalid and insert the new one, preserving an audit trail.
Privacy guard - secrets never get stored
Every candidate memory and profile value passes a privacy filter before it's
written. Anything matching a secret/PII pattern - API keys (sk-…, sk-ant-…,
Google, GitHub, Slack tokens), PEM private keys, password:/secret:
assignments, SSNs, credit-card-like digit runs - is dropped. The extractor
prompt is also told never to emit secrets, so this is defence in depth.
Commands
Type / in the chat input for autocomplete. Saving requires memory to be on
(and not incognito).
| Command | Effect |
|---|---|
/remember <fact> | Save a fact immediately (high priority) |
/global <fact> | Save a fact for all your chats and projects; only you see it |
/team <fact> | Save a fact for everyone in this workspace (your team) |
/forget <text> | Forget memories whose content matches the text |
/memories | Show how many memories Lucy holds, plus a few recent ones |
/incognito | Toggle "no capture" for this session |
/remember and /global are explicit saves and carry more weight than
auto-extracted memories, so they rank higher in recall. /incognito is a
per-session switch - while it's on, Lucy neither recalls nor captures
memory: the retrieval block is skipped for the turn and the end-of-turn
extraction is skipped entirely.
You: /remember the staging DB is on port 6543
Lucy: 🧠 Saved to memory.
You: /global I prefer concise answers with code first
Lucy: 🧠 Saved to memory.
You: /forget staging DB
Lucy: 🗑️ Forgot 1 memory matching "staging DB".
Visibility
| Visibility | Who sees it |
|---|---|
| Private (default) | Only you |
Team (/team) | Everyone in the workspace (team) it was saved in |
| Global | Lucy's own memory (her identity and what an admin teaches her). No user owns it; everyone gets it |
Memories are isolated per user by row-level security in connected mode, and per
browser in standalone mode. A memory that belongs to a user is never shown to another user,
whatever its visibility (a /global note included). Forgetting with /forget archives matching memories
immediately.
Your controls - Settings → Memory
The user-facing panel lets you:
- Turn memory on or off (in connected mode this reflects the admin gate; in standalone mode it's your own local switch).
- Toggle incognito for the current session.
- See storage usage - memory count, entity count, and size.
To review or prune what Lucy holds, use the chat commands: /memories lists a
recent sample, and /forget <text> archives anything matching.
Admin settings (connected mode only)
Deployment-wide memory settings live in the admin panel and require the admin
role to change. They write a single config row (lucy.memory_settings):
| Setting | What it does |
|---|---|
| Enabled | Master switch for memory across the deployment |
| Contradiction policy | supersede (keep current truth) vs keep_history (audit trail) |
| Deletion grace window | Days an archived memory is retained before it's purged for good |
| Embedder | Which model turns text into vectors (see below) |
The pluggable embedder
The embedder is what makes recall work by meaning instead of keywords. It's swappable, with presets that fill provider, model, base URL, and dimensions together:
- Cloudflare Workers AI
@cf/baai/bge-m3(1024) - recommended. It handles Croatian, English and 100+ other languages, is cheap, and needs only a Cloudflare account ID and an API token with the Workers AI permission. Lucy callsPOST https://api.cloudflare.com/client/v4/accounts/<id>/ai/run/@cf/baai/bge-m3with{ "text": [...] }and readsresult.data, up to 100 texts per call. Base URL may be left blank (or set to an AI Gateway URL). - OpenAI
text-embedding-3-small(1536) or3-large(3072). - Local Ollama (e.g.
embeddinggemma,nomic-embed-text,mxbai-embed-large,bge-m3) athttp://localhost:11434/v1- no API key, no cloud calls, but only where Ollama is installed and running on the Lucy server. - Other OpenAI-compatible providers (Google, Mistral, Jina, Voyage) work by base URL alone; Cohere is supported through its own adapter.
The API key / token is stored encrypted and is server-only - it's never returned to the browser; the panel shows only "saved, ends ••••1234". A key belongs to one provider: switching provider without typing a new key drops the old one.
Server env fallback (Cloudflare). When nothing is saved in Admin, Lucy uses
CLOUDFLARE_AI_API_TOKEN and CLOUDFLARE_ACCOUNT_ID from the server env (the
panel says "using the server's ..."). With no memory settings at all and both
set, Lucy uses Cloudflare bge-m3.
Test embedder. The button embeds one short sentence with what is in the form (saved or not) and shows the size and time ("Works: 1024 dimensions in 180 ms") or the clear error (wrong token, unknown account, size mismatch, ...). Save embedder runs the same test first and refuses to save a failing or wrong-size embedder; Save anyway skips the test.
Changing the embedder re-indexes in the background. A new model or size makes every stored vector meaningless, so on Save Lucy:
- reshapes the
embeddingcolumn when the size changes (the vectors are cleared), or clears the vectors when only the model changes; - rebuilds them in batches in the background, showing "Re-indexing 340 of 1,200" in the panel. Keyword recall works the whole time; vector recall covers each memory as soon as it has its new vector;
- keeps its progress in
memory_settings, so after a restart it resumes where it stopped. A failing batch is retried every ~2 minutes; after 5 failures in a row it stops and the panel offers Resume.
Fill missing vectors gives a vector to memories saved while the embedder was down. Memories themselves are never touched; only their vectors are rebuilt.
Graceful degradation - the lexical fallback
If no embedder is configured, or the embedding provider errors, memory does not break. Vector search simply returns nothing for that query and recall falls back to Postgres full-text search alone. New memories are still stored (just without a vector until an embedder is available - use Fill missing vectors). Failures are logged at most once every 5 minutes (with a count), and the panel shows "Embedder failing - recall uses keywords only" with the last error. This is the same lexical engine that standalone mode uses by default.
Related
- Chat & models - slash commands and the model you chat with
- Workflows - the Knowledge Base node recalls your memories inside a pipeline
Team facts
Facts saved with /team or /company belong to everyone in your company workspace. Lucy always has them in mind there, not only when your question happens to match them, and she gets up to the 30 newest. /memories shows how many you have of your own and how many the team shared. A personal workspace has no team facts.
The Knowledge page
Knowledge in the sidebar shows what your team has taught Lucy, newest first, 30 at a time; more load as you scroll (or with Show more). Search looks through all of it, not only what is on screen.
- Teach Lucy opens a popup: type or paste a text or a whole document. Lucy splits it into pieces she can recall one by one (one fact per paragraph).
- Team tab: everyone in the workspace adds; the person who added a piece, or an owner or admin, removes it.
- Lucy (global) tab (Lucy admins only): facts Lucy uses for every user on this server.
Documents
Knowledge › Documents holds files Lucy reads and uses in her answers: PDF, Word (.docx), Excel (.xlsx), CSV, text and Markdown, up to 25 MB each.
- Add document opens a popup: pick the file and who can use it. Only me (Lucy uses it only in your chats), Team (everyone in the workspace; owners and admins only) or Lucy (global) (every user; Lucy admins only).
- Lucy reads it in the background: Queued, Reading, then Ready. Could not read says why, for example a scanned PDF with no text (reading scans comes later).
- When an answer uses a document, Lucy puts a number like [1] after the sentence, and under the answer a chip shows the document and page. Click it to open the file (a PDF opens at that page).
- A file you sent in a chat can go in too: the book icon on its card, then Only me or Team.
- The pencil changes who can use a document; Archive stops Lucy using it. The file itself stays in Account › Files.
- Search finds words without the accents too: "racun" finds "račun".
Receipts and invoices
Send a receipt or an invoice in the chat (a photo, a PDF or an e-invoice XML) and Lucy reads it in the background.
- Under the file you see Lucy is reading the receipt…, then a card: seller, date, total, VAT by rate and the number of items.
- Anything that does not add up is shown in amber. Edit opens a popup with every field; Save and confirm saves your changes and confirms.
- Confirm when the numbers are right. Lucy uses only confirmed receipts in answers, for example "How much did I pay at Konzum in October?".
- You see your own receipts. Owners and admins see all receipts in the workspace.
- If Lucy cannot read it, the card says why and offers Try again.