Lucy AI/Docs
GitHubOpen app

Getting started

  • Introduction
  • Quick start
  • Desktop app

Using Lucy

  • Chat & models
  • Skills
  • Members
  • Calendar & meetings
  • Files in chat
  • Memory
  • Personas
  • Connectors
  • Workflows
  • Channels
  • Voice
  • Security & 2FA
  • Themes & account

Developers

  • Architecture
  • Self-hosting
  • Embedding Lucy
  • HTTP API
  • CLI
  • MCP server
  • Contributing

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)
StoragePostgres (lucy.memories), RLS-isolated per userYour browser's IndexedDB
RecallHybrid: embeddings + full-text, fusedKeyword (lexical) only
EnableAdmin toggles Settings → MemoryYou toggle the local switch
EmbedderAdmin-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:

TypeWhat it holdsHalf-lifeInjected as
SemanticStable facts & preferences ("prefers Tailwind")60 daysFacts
PragmaticWorking style / current intent10 daysWorking style
EpisodicWhat happened, and when ("Q3 launch moved to October")30 daysRecently

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:

  1. Vector search - your message is embedded and compared against memory embeddings by cosine distance (pgvector / halfvec, HNSW index).
  2. Full-text search - the same message runs as a Postgres websearch_to_tsquery against a generated tsvector column.
  3. 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).
  4. 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:

OpMeaning
ADDGenuinely new - insert it
UPDATEReplaces an existing memory (a fact changed)
MERGEFolds into an existing memory
SKIPRedundant 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).

CommandEffect
/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
/memoriesShow how many memories Lucy holds, plus a few recent ones
/incognitoToggle "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

VisibilityWho sees it
Private (default)Only you
Team (/team)Everyone in the workspace (team) it was saved in
GlobalLucy'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):

SettingWhat it does
EnabledMaster switch for memory across the deployment
Contradiction policysupersede (keep current truth) vs keep_history (audit trail)
Deletion grace windowDays an archived memory is retained before it's purged for good
EmbedderWhich 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 calls POST https://api.cloudflare.com/client/v4/accounts/<id>/ai/run/@cf/baai/bge-m3 with { "text": [...] } and reads result.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) or 3-large (3072).
  • Local Ollama (e.g. embeddinggemma, nomic-embed-text, mxbai-embed-large, bge-m3) at http://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:

  1. reshapes the embedding column when the size changes (the vectors are cleared), or clears the vectors when only the model changes;
  2. 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;
  3. 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.
Files in chatPersonas