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 daemonresolves and supervises it. If Lemonade isn’t installed yet, rungaia 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.Via the Agent UI (recommended)
- Launch the Agent UI:
gaia chat --ui - Open Memory in the sidebar, then the Advanced tab.
- 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)
~/.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:gaia chat --ui and click the Brain icon to see every memory, filterable and editable.
How It Works
Agent memory operates on four principles:- Store automatically once enabled — conversations, tool calls, errors, and preferences are captured without manual effort
- 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.
- 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.
- Be temporally aware — the agent knows the current time, what is coming up, what is overdue, and proactively surfaces time-sensitive items
~/.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.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.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 usesrecall 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.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.
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:
Sensitive Data
Some knowledge is private — email addresses, API tokens, health information, financial data. Thesensitive 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.
Entity Linking
For managing contacts, apps, and services, the agent associates knowledge with specific entities using atype: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 thedue_at field on memory entries.
How reminders work
- You mention something time-sensitive — the agent stores it with a
due_atdate, which the Memory page shows on the reminder (“Due Fri, Oct 30”, or “Was due …” once it has passed) - As the date approaches, the agent sees it in its per-turn context and proactively mentions it
- After mentioning it, the agent marks
reminded_atso it does not repeat itself - If the due date passes, the item appears as overdue until resolved
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 ownremember 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.
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
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 statuslists 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 --uiMemories 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, andgaia 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_bylink 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
pytestfails until the agent addsenv 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, orGAIA_PROJECT_ROOTwhen 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.
~/.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=1turns off both synthesis and recall."skill_synthesis": { "enabled": false }inmemory_settings.jsonskips synthesis while leaving the rest of memory active.- A procedure you disable (
enabled = 0) or that has been superseded is never recalled.
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:CLI Reference
System context (versions, hardware, apps)
System facts — GAIA/Lemonade versions, OS, CPU/GPU/RAM, installed apps — are captured assystem-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.
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