Skip to main content
GAIA Agent Memory is a persistent knowledge system that gives your agent a second brain. It remembers facts, preferences, errors, and workflows across sessions — so every conversation picks up where the last one left off. All data stays local on your machine in a single SQLite file.
First time here? Complete the Quickstart (For Developers) or Manual Install guide first, then come back to enable memory.

Prerequisites

Before using Agent Memory, make sure you have the following in place:
  • Install path: Developer install — clone the repo and install from source:
  • Extras required: [dev,rag] — [rag] provides the FAISS index used for memory recall; [dev] adds the developer toolchain
  • Model server: nothing to start — gaia daemon resolves and supervises it. If Lemonade isn’t installed yet, run gaia init
  • Example files referenced in this guide are inside the cloned repo under examples/
Memory is currently integrated into the Chat Agent. Any agent built on the GAIA Agent base class can add memory via the MemoryMixin — see the Memory SDK Reference for developer details.
Memory is on by default (beta). This feature is still under active development — every new GAIA install ships with memory on, so the agent starts recalling and saving facts right away. Turn it off (see Turn Memory On or Off below) to get standard, non-persistent chat behavior. With memory disabled, prompt construction and session reset do no memory work. The SDK memory_store accessor returns None for a disabled session; callers can use memory_unavailable_message() to explain why.

Turn Memory On or Off

Memory is on by default, in the terminal UI and the Agent UI alike. Turning it off stops all memory writes on this machine until you turn it back on; a private chat pauses it for that chat only. To keep even a chat’s first message out of memory, click Memory on next to the message box so it reads Private before you send it (while memory is turned off it reads Memory off and can’t be clicked); an open chat can be made private with the eye button in its header, which stays filled while the chat is private. Either switch takes effect on the next message, in open chats as well as new ones; the Agent UI’s background goal runs and scheduled tasks follow it too.
  1. Launch the Agent UI: gaia chat --ui
  2. Open Memory in the sidebar, then the Advanced tab.
  3. Use the toggle next to Memory. The agent picks up the change on its next message — no restart needed.

Via the API (for headless / scripted setups)

Verify it stuck:
The email agent is not available in private chats or while memory is turned off. The chat HTTP API stops these requests before sending them to the email agent, which does not yet support these settings. Use the GAIA agent to continue with memory disabled. While memory is off, none of the behaviors on this page (cross-session recall, automatic extraction, the Memory page) are active — sessions run in “incognito” mode, nothing is written to ~/.gaia/memory.db, and the agent says memory is turned off when asked to remember something.
While memory is on, conversations are summarized into ~/.gaia/memory.db — a plaintext SQLite file (not encrypted). The Sensitive Data section below explains the sensitive flag for controlling system-prompt visibility; do not store passwords or tokens in agent memory.

Try It Right Now

With memory enabled (above), here’s what a second brain feels like. Teach it something in one session, then start a fresh one and watch it recall:
The agent remembered across sessions — no copy-paste, no notes app. Run gaia chat --ui and click the Brain icon to see every memory, filterable and editable.

How It Works

Agent memory operates on four principles:
  1. Store automatically once enabled — conversations, tool calls, errors, and preferences are captured without manual effort
  2. Recall naturally — each turn, the few stored memories most relevant to your message are added to the agent’s context automatically, each with the date it was learned. For anything more, the LLM searches with its own tools: hybrid semantic+keyword search finds memories by meaning, not just exact words.
  3. Learn continuously — LLM extraction from every conversation, not just regex patterns. The agent sees what it already knows and decides what’s new, what’s changed, and what’s contradicted — like intelligent memory management.
  4. Be temporally aware — the agent knows the current time, what is coming up, what is overdue, and proactively surfaces time-sensitive items
Everything is stored in a single file at ~/.gaia/memory.db (SQLite with WAL mode for concurrent reads). No cloud services, no external dependencies.

Quick Start

1

Bootstrap your memory

Run the day-zero onboarding flow. The agent asks a few questions about you and optionally scans your system to discover projects, tools, and interests:
You can run just the conversational part or just the system discovery:
The questions adapt to your answers — say you are a student and the follow-up asks about coursework, not deployment pipelines. When the questions are done, everything the agent learned is shown back as a list and stored one item at a time on your approval ([Y] store · [n] skip · [q] stop). Nothing reaches the database unreviewed.
Bootstrap is repeatable. Run it again anytime to refresh the agent’s understanding. New discoveries will not overwrite items you have manually edited.
2

Check memory status

See how much the agent knows and how the memory is structured:
This shows counts by category (fact, preference, error, skill, note, reminder, profile, system, permission), context (work, personal, global), total conversations, tool call stats, and database size.It also shows Search vectors — how many entries can be found by meaning. An entry saved while the embedding model was unavailable is kept, but only keyword recall finds it until it is re-embedded; status lists these as Without vector. See Memories saved without a search vector to repair them.
3

Start chatting

With memory on (see Turn Memory On or Off above), the agent injects relevant knowledge into its system prompt and uses memory tools during conversation:
Try saying things like:
  • “Remember that our project uses React 19 with the app router”
  • “I prefer concise answers with code examples”
  • “What do you know about me?”
  • “What did we talk about last week?”

Memory Tools

The agent has 6 memory tools it can use during conversation. You do not call these directly — the LLM decides when to use them based on your conversation.

remember

Stores a new fact, preference, error pattern, or skill in persistent memory.

recall

Searches memory for relevant knowledge using hybrid semantic+keyword search — it finds concepts, not just exact keywords. If you say “frontend framework,” it matches memories about React, Vue, and Angular, even if those exact words aren’t in your query.
Recall also supports temporal filtering with time_from and time_to. The agent converts natural language dates (“last week”, “in March”) to concrete time ranges using the current date it always knows:

update_memory

Modifies an existing memory entry. The agent uses recall first to find the ID, then updates it.

forget

Removes one memory, by its ID or by your own words for it (“allergic to shellfish”). Words erase a memory only when exactly one clearly matches; otherwise nothing is erased and GAIA checks which one you meant. GAIA won’t learn it again from the old conversations that mentioned it. If you tell GAIA again later, it learns it again.
Searching past conversations doesn’t bring a forgotten memory back: a turn said before you forgot it is left out of the results.

forget_everything

Erases everything GAIA remembered about you and your chats: every fact, preference and reminder, sensitive ones included, and the stored past conversations and tool history. GAIA asks you to approve it first, because it can’t be undone. Other open chats stop using the erased memories from their next message. Two things are kept. Skills GAIA learned for doing tasks (procedural memory and the adjustments it made to installed skills) stay; gaia skill deltas <skill> --reset undoes what it learned about a skill, and deleting the memory file removes all of it. Chats listed in the sidebar, the current one included, stay until you delete them there. Delete all memories on the Memory page erases the same things.

search_past_conversations

Searches across all past conversation sessions by keyword (query), time range (days or time_from/time_to), or both.

Your Second Brain

Memory turns GAIA into a personal knowledge system that grows smarter with every conversation. Common uses:
  • Daily journal — log your work; recall it weeks later by date (“what did I work on the first week of April?”).
  • Meeting notes — paste standup notes; the agent extracts per-person facts and deadlines automatically.
  • Research notes — save article summaries and find them later by concept, not just keywords.
  • Personal reminders — set due dates (including recurring ones); the agent surfaces them proactively.
  • Contact profiles — knowledge about people accumulates across conversations, linked to entities.
  • Error learning — when a tool fails, the agent remembers the pattern and avoids it next time.
A representative example — proactive, time-aware reminders:
Recurring reminders advance their date automatically each time they fire (e.g. “remind me to do a weekly review every Friday at 5pm”).

Knowledge Categories

Every memory entry belongs to one of six categories: The agent automatically categorizes knowledge when you ask it to remember something. You can also specify the category explicitly:

Context Scoping

Different areas of your life produce different knowledge. Without scoping, the agent mixes work deployment commands with personal dentist appointments. Contexts keep them separate. In a default session the active context is global, and the system prompt includes memories from every context. An agent that sets a specific context sees that context plus global, and new memories are stored under the active context:
gaia chat runs in the default global context. The model can’t choose a context when it stores a memory, so a memory can’t be filed somewhere no later session reads it.

Sensitive Data

Some knowledge is private — email addresses, API tokens, health information, financial data. The sensitive flag controls how this data is handled: The agent can still access sensitive data when you explicitly ask for it via recall — it just will not be broadcast in the system prompt where it could leak into logs or debugging output.
Sensitive data is still stored in plaintext in ~/.gaia/memory.db. The sensitive flag controls visibility, not encryption. Do not store passwords or tokens in agent memory — use your OS keyring for credentials.GAIA refuses to remember anything shaped like a credential: API keys, passwords, PINs and passcodes, card security codes, card numbers and SSNs. The same shapes are replaced with [secret removed] before a turn is saved to the conversation log, so past-conversation search can’t read them back. Detection is by shape, so a secret with no recognizable form can still slip through.

Entity Linking

For managing contacts, apps, and services, the agent associates knowledge with specific entities using a type:name convention: Multiple entries can share an entity, building a profile over time. When you say “email Sarah about the roadmap,” the agent calls recall(entity="person:sarah_chen") to get her email and preferences.

Temporal Awareness

The agent always knows the current date and time. It can track commitments and deadlines using the due_at field on memory entries.

How reminders work

  1. You mention something time-sensitive — the agent stores it with a due_at date, which the Memory page shows on the reminder (“Due Fri, Oct 30”, or “Was due …” once it has passed)
  2. As the date approaches, the agent sees it in its per-turn context and proactively mentions it
  3. After mentioning it, the agent marks reminded_at so it does not repeat itself
  4. If the due date passes, the item appears as overdue until resolved
The same mechanism powers accountability — commit to something (“I’ll exercise 3 times this week”) and the agent checks in proactively when the deadline nears.

Intelligent Extraction

After each conversation turn (with memory enabled), the agent automatically decides what’s worth remembering — without you saying “remember.” This isn’t pattern matching; the LLM sees your existing memory and the new conversation, and decides whether to ADD new knowledge, UPDATE a changed fact (old version preserved with lineage), or DELETE something you’ve contradicted. This happens after your answer is on screen, in the background, so it never adds to how long you wait for a reply. A fact you state may take a few more seconds to appear on the Memory page than the answer itself did. It extracts information useful in future conversations — facts, preferences, project details, people, deadlines — and skips greetings, confirmations, ephemeral details, and narration of the current session (where you’re working, what was just changed). For example, “we standardized on Python 3.12 and I’m using a Ryzen 9 9950X” stores two facts but ignores subjective asides like “it’s much faster.” Only what you said about yourself is stored. What GAIA read during the turn is not: summarizing a PDF, looking up the weather, or reading a note doesn’t turn the document’s contents into facts about you. A claim that appears only in the agent’s own answer is not stored either, because the answer can be wrong, and a permission refusal is not, because permissions change. The agent’s own remember and update_memory calls follow the same rule: text from a file, web page or tool result is saved only when your message asks to keep something, so a line planted in a document can’t make itself one of your saved details. A new message stops an extraction that is still running, so your reply never waits behind it; the extraction runs again once you pause.
Intelligent extraction kicks in for messages of 5+ words. Short messages like “yes” or “thanks” are skipped. The LLM’s explicit memory tools (remember, update_memory, forget) still handle anything the auto-extraction misses.

Memory page

The Agent UI has a Memory page for seeing and correcting what GAIA knows about you. Click Memory in the sidebar to open it.

About you

The page opens on What GAIA knows about you: the facts, preferences, reminders and notes GAIA uses in every chat, grouped and in plain words, each with where it came from (“Picked up in a chat”, “You added this”).
  • Edit an item in place when it’s wrong.
  • Forget an item in one click. GAIA won’t learn it again from old chats; Undo restores it.
  • Add something GAIA should know, like “I prefer short answers”.

Advanced

The Advanced tab keeps the full view for troubleshooting:
  • Stats overview — total memories, sessions, tool calls, success rate, and embedding coverage
  • Knowledge browser — filterable, sortable table of all memory entries, including confidence and source, with inline editing
  • Tool performance — per-tool success rates, error history, average duration. Memory tools (remember, recall, update_memory, forget, forget_everything, search_past_conversations) are not logged, so they never appear here or in the Tool Calls count. A call that was denied or refused before it ran is listed under Denied and is left out of the call count, success rate and error history, since the tool never ran
  • Upcoming and overdue — time-sensitive items due soon or past due
  • Conversation history — searchable archive of all past sessions with consolidation status. Deleting a chat deletes it here, and its tool calls from Tool performance; what GAIA learned from it stays under About you. Chats from earlier GAIA versions were filed under a random id, so they stay here until memory prunes them, about 90 days on, or you use Delete all memories
  • Superseded items — toggle to see fact history and how knowledge evolved over time
  • Settings — turn memory on or off, and clear or re-initialize it
From the knowledge browser you can create entries (stored with high confidence and embedded right away, so recall by meaning finds them at once), edit any field, delete entries, toggle sensitive to hide or show private data, search with hybrid semantic+keyword search, and filter by category, context, or entity.

Maintenance actions

The Advanced tab also provides maintenance tools for keeping your memory healthy:
  • Consolidate — distill old conversation sessions into durable knowledge notes
  • Rebuild Embeddings — embed the knowledge items that have no search vector yet (the ones gaia memory status lists as Without vector)
  • Reconcile — scan for contradictory facts across sessions and resolve them automatically
To launch the Agent UI with the Memory page: gaia chat --ui

Memories saved without a search vector

If the embedding model is unreachable when a memory is written, the memory is still saved, but recall by meaning cannot find it until it is re-embedded (keyword recall still can). The agent logs one warning per session naming the first affected memory and how to repair it, and gaia memory status shows the running total as Without vector. To repair, either:
  • Start any memory-enabled agent with the embedding model loaded — it re-embeds up to 100 missing vectors on every start.
  • Click Rebuild Embeddings on the Memory page’s Advanced tab (gaia chat --ui) to embed up to 500 at a time.

Terminal UI: /memory

No browser handy? The Terminal UI (gaia-tui) has a read-only /memory command in the chat screen — grouped by category, with counts, confidence, and when each entry was last touched, so you can see the actual rows instead of asking the agent to summarize its own memory (which can omit or misremember what it stored). It only reads; editing, deleting, and adding are still Agent UI features. /memory works the same way regardless of how the flagship agent got onto your machine — installed standalone, or hub-installed via gaia init and run as a daemon-supervised sidecar. The one thing that can still block it is an out-of-date sidecar: a peer built before this contract has no memory route at all, and /memory says so and names the command that updates the agent rather than failing silently.

How Memory Improves Over Time

These mechanisms run automatically — you don’t need to manage them.
  • Confidence scoring — every entry has a 0.0—1.0 confidence. Newly created entries start lower for auto-captured items (LLM-extracted and discovery at 0.4; tool-stored, error, and consolidation at 0.5) and higher for user-created dashboard entries (0.8). Each recall adds +0.02, so frequently-used memories rank higher in the system prompt.
  • Confidence decay — entries not accessed for 30+ days are multiplied by 0.9 at most once a month (checked at session start, and never within a month of you confirming one), so stale knowledge fades in favor of what you actively use.
  • Fact lineage — when a fact changes, the old version is kept with a superseded_by link and its original timestamp, so you can answer “what framework were we using in March?” The dashboard’s superseded view shows the full chain.
  • Automatic error learning — a tool call that ran and failed is stored as an error pattern; the next session’s system prompt lists it, dated, under “Problems seen before” so the agent doesn’t repeat it. The list is framed as notes, not orders: a URL, file or command you hand the agent is still tried, and a passing failure (a timeout, a 503) is marked as one. Calls the permission layer refused — including ones you declined at the confirmation prompt — are not stored (they describe your current permissions, which can change) and never clear what is already stored; an error is dropped as soon as the same operation (the same program or path) actually runs and succeeds.
  • Lessons from fixes — when a call fails and a changed call of the same kind then works in the same turn (for example pytest fails until the agent adds env TOYBOX_CLOCK=frozen), GAIA keeps both calls as a lesson for that project. Later sessions anywhere in the same project see it in their system prompt with the date it was learned; another project never does. Scope is the project root — the repository you are working in, or GAIA_PROJECT_ROOT when you set it — so approving a file elsewhere mid-session doesn’t move your lessons. It gains confidence each session the fix works again, is dropped if the fix itself fails, and a newer fix for the same operation replaces the older one rather than piling up variants.
  • Session consolidation — conversations older than 14 days are distilled into durable notes (extracted facts live indefinitely; raw conversations are pruned at 90 days, but only once their whole session has been distilled), so old context is never lost.
  • Background reconciliation — on startup the agent resolves contradictory facts across sessions, superseding the older item and boosting the newer (and reinforcing) one’s confidence.

Procedural memory (skills)

Beyond remembering facts, the agent learns procedures — the multi-step tool recipes it has already run successfully. When the same kind of goal succeeds several times with the same shape of work, GAIA distils that successful tool sequence into a reusable skill and stores it as a procedure. The next time a similar goal comes up, the agent recalls the proven recipe and reuses it instead of re-planning from scratch. This is automatic: there is no command to run and no skill to install. Synthesis runs during the startup maintenance pass, and a matching skill is injected silently into the agent’s planning context. A procedure is only synthesized when all of these hold:
  • the same goal succeeded at least 3 times (clustered by goal similarity ≥ 0.82),
  • the success rate across those attempts is at least 80%, and
  • each successful run was a real multi-step sequence of at least 3 tool calls.
These thresholds live in ~/.gaia/memory_settings.json under a skill_synthesis section, so you can tighten or relax them per machine. Synthesized skills follow the same lineage rules as facts: a better recipe supersedes an older one rather than overwriting it, and nothing is deleted automatically. Off switches:
  • GAIA_MEMORY_DISABLED=1 turns off both synthesis and recall.
  • "skill_synthesis": { "enabled": false } in memory_settings.json skips synthesis while leaving the rest of memory active.
  • A procedure you disable (enabled = 0) or that has been superseded is never recalled.
Run gaia memory status to see how many procedures have been synthesized.

Privacy

100% Local

All memory is stored in a single SQLite file at ~/.gaia/memory.db. Nothing is transmitted to any server or cloud service.

User Control

You can view, edit, and delete any memory entry via the dashboard or CLI. The agent only knows what you approve.

Bootstrap Consent

System discovery scans are opt-in. The agent shows you what it found and asks for approval before storing anything.

Sensitive Flagging

Mark any entry as sensitive to exclude it from the system prompt. Browser history and email addresses are auto-flagged during bootstrap.

Deleting all memory

To reset discovery-sourced items while preserving your manual edits:
To completely delete all memory, remove the database file:

CLI Reference

System context (versions, hardware, apps)

System facts — GAIA/Lemonade versions, OS, CPU/GPU/RAM, installed apps — are captured as system-category memories. Collection is opt-in: the system_context_enabled flag in ~/.gaia/memory_settings.json defaults to false. Enable it from the Agent UI Memory page (Advanced tab) or by running gaia memory bootstrap --system (which offers to turn it on). Once enabled, system facts auto-refresh on agent startup when either:
  • a tracked version (GAIA or Lemonade Server) no longer matches the live value — so version facts update immediately after an upgrade, or
  • the newest fact is more than 7 days old.
Each refresh clears the old system entries before re-collecting, so values are replaced rather than duplicated. To force a refresh yourself, run gaia memory bootstrap --system.

Next Steps

Memory SDK Reference

MemoryMixin API, MemoryStore class, and code examples for adding memory to custom agents

Agent UI

Desktop interface with a Memory page for seeing and correcting what GAIA knows

Agent SDK

Chat SDK for building conversational agents programmatically

Build Your First Agent

Create a custom agent with tools and memory in minutes