Agent Memory - GAIA SDK

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:

git clone https://github.com/amd/gaia.git
cd gaia
uv venv .venv --python 3.12
source .venv/bin/activate        # Windows: .venv\Scripts\activate
uv pip install -e ".[dev,rag]"

Extras required: [dev,rag] — [rag] provides the FAISS index used for memory recall; [dev] adds the developer toolchain
Lemonade server must be running before you start:
lemonade-server serve
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 opt-in (beta) and disabled by default. This feature is still under active development — every new GAIA install ships with memory off, so you’ll see standard chat behavior until you turn it on. See Enable Memory below before trying any examples on this page.

Enable Memory

Memory is off by default. Turn it on once and it stays on for every future gaia chat session on this machine.

Via the Agent UI (recommended)

Launch the Agent UI: gaia chat --ui
Click the Brain icon in the toolbar to open the Memory Dashboard.
Click the Off toggle next to Memory; a confirmation modal appears. Click Enable Memory in the modal to confirm. The agent picks up the change on its next message — no restart needed.

Via the API (for headless / scripted setups)

curl -X PUT http://localhost:4200/api/memory/settings \
  -H "Content-Type: application/json" \
  -H "X-Gaia-UI: 1" \
  -d '{"memory_enabled": true}'

Verify it stuck:

curl http://localhost:4200/api/memory/settings
# → {"memory_enabled": true, ...}

Until you enable memory, none of the behaviors on this page (cross-session recall, automatic extraction, the Memory Dashboard’s knowledge browser) will activate — sessions run in “incognito” mode and nothing is written to ~/.gaia/memory.db.

Once enabled, 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:

# Session 1
gaia chat
You: "Remember that I'm working on the GAIA memory system, and that
      standup is tomorrow at 10am -- Sarah is presenting the API migration."
Agent: "Got it -- I've noted your project and linked Sarah to the standup."

# Session 2 (close the chat, start fresh)
gaia chat
You: "What's coming up?"
Agent: "You have a standup at 10am -- Sarah is presenting the API migration."
You: "What do you know about Sarah?"
Agent: "Sarah is presenting the API migration results at tomorrow's standup."

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:

Store automatically once enabled — conversations, tool calls, errors, and preferences are captured without manual effort
Recall naturally — hybrid semantic+keyword search finds memories by meaning, not just exact words. The LLM decides when to search using its own tools (no forced pre-query step).
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

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

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:

gaia memory bootstrap

You can run just the conversational part or just the system discovery:

gaia memory bootstrap --chat-only    # Questions only
gaia memory bootstrap --discover     # System scan only

Bootstrap is repeatable. Run it again anytime to refresh the agent’s understanding. New discoveries will not overwrite items you have manually edited.

Check memory status

See how much the agent knows and how the memory is structured:

gaia memory status

This shows counts by category (fact, preference, error, skill, note, reminder), context (work, personal, global), total conversations, tool call stats, and database size.

Start chatting

With memory enabled (see Enable Memory above), the agent injects relevant knowledge into its system prompt and uses memory tools during conversation:

gaia chat

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 5 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.

You: "Remember that Sarah's email is [email protected]"
Agent: "Saved -- I've linked that to Sarah's contact profile."

You: "I have a course starting on March 25th"
Agent: "Noted. I'll remind you as it gets closer."

You: "I always want dark mode in code examples"
Agent: "Got it, I'll apply that preference going forward."

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.

You: "What do you know about my deployment process?"
Agent: [recalls skill entries about deployment workflow]

You: "What do you know about Sarah?"
Agent: [recalls all entries linked to entity person:sarah_chen]

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:

You: "What did we discuss about deployment last week?"
Agent: "Last week you pushed the staging deploy and hit a kubectl
        permissions error. You resolved it by adding the service
        account role."

update_memory

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

You: "Actually, we switched from React to Vue"
Agent: "Updated -- I've changed your project's framework from React to Vue 3."
       [agent recalls the React fact, updates it in place, marks old as superseded]

You: "What's today looking like?"
Agent: "You have a busy afternoon. By the way, your online course
        starts in 3 days -- just a heads-up."
       [agent internally marks reminded_at so it won't surface this again]

forget

Removes a specific memory entry by ID.

You: "Forget what you know about the old deployment process"
Agent: [recalls the entry, deletes it]

search_past_conversations

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

You: "What did we discuss about database migration?"
Agent: "Found 3 conversations mentioning database migration:
        two sessions last month about the Postgres schema, and
        one this week where you decided to add a new index."

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:

You: "Remind me to submit the expense report by Friday"
Agent: "Done -- I'll make sure to mention it before Friday."

— Thursday afternoon, talking about code —

You: "Can you refactor this function?"
Agent: "Sure, here's the refactored version. By the way,
        your expense report is due tomorrow -- don't forget to submit it."

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:

Category	What it stores	Example
fact	Things about you, your projects, your world	”User’s project uses React 19 with app router”
preference	How you want the agent to behave	”User prefers concise answers”, “Always use dark mode”
error	Tool error patterns to avoid in the future	”pip install torch fails without —index-url on this machine”
skill	Learned workflows and multi-step patterns	”To deploy: run tests, build, push to staging, verify, promote”
note	Free-form observations, journal entries, or meeting notes	”Standup 2026-04-01: API migration complete”
reminder	Time-sensitive items to follow up on	”Check if the PR was merged by Friday” (use with `due_at`)

The agent automatically categorizes knowledge when you ask it to remember something. You can also specify the category explicitly:

You: "Remember as a skill: to set up a new React project,
      run npx create-next-app, then install tailwind, then configure eslint"

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.

Context	When it is active	What it contains
`global`	Always included	Universal preferences, your name, timezone
`work`	Work-related tasks	Colleagues, project details, work tools
`personal`	Personal assistant mode	Appointments, health goals, personal contacts
Custom (e.g., `project-x`)	User-defined per project	Project-specific facts, skills, errors

The agent’s system prompt always includes global items plus items from the active context. You can switch contexts mid-session:

You: "Switch to my personal context"
Agent: "Switched to your personal context."

You: "Remember that my dentist appointment is Thursday at 2pm"
Agent: "Done -- dentist appointment Thursday at 2pm, stored in your personal context."

When you use gaia chat, the default context is global. You can start with a specific context by telling the agent, or programmatically via init_memory(context="work") in the SDK.

Sensitive Data

Some knowledge is private — email addresses, API tokens, health information, financial data. The sensitive flag controls how this data is handled:

Where	Normal (default)	Sensitive
System prompt	Included	Never included
`recall` results	Returned	Returned (explicit query only)
Tool history args	Full args logged	Args redacted to keys only
Memory Dashboard	Normal display	Content blurred until clicked

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.

You: "Remember Sarah's email is [email protected], mark it as sensitive"
Agent: "Saved -- I've marked Sarah's email as private and linked it to her profile."

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.

Entity Linking

For managing contacts, apps, and services, the agent associates knowledge with specific entities using a type:name convention:

Entity pattern	Example knowledge
`person:sarah_chen`	”Sarah Chen, VP Engineering, [email protected]”
`person:sarah_chen`	”Sarah prefers morning meetings”
`app:vscode`	”User prefers dark mode, 4-space tabs”
`service:gmail`	”User’s work email is [email protected]”
`project:gaia`	”Project uses Python 3.12, uv for package management”

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

You mention something time-sensitive — the agent stores it with a due_at date
As the date approaches, the agent sees it in its per-turn context and proactively mentions it
After mentioning it, the agent marks reminded_at so it does not repeat itself
If the due date passes, the item appears as overdue until resolved

Day 1:  You: "I have a course starting next Tuesday"
        Agent: "Noted -- I'll remind you as it gets closer."
Day 5:  You: "What's the weather like?"
        Agent: "It's sunny. By the way, your online course starts in 3 days."
Day 8:  You: "Good morning"
        Agent: "Good morning! Your course starts today. How's it going?"

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 alongside 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. It extracts information useful in future conversations — facts, preferences, project details, people, deadlines — and skips greetings, confirmations, and ephemeral details. 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.”

Intelligent extraction kicks in for messages of 20+ 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 Dashboard

The Agent UI includes a full-page Memory Dashboard for viewing and managing everything the agent knows. Click the Brain icon in the toolbar to open it.

gaia chat --ui

What you can see

Stats overview — total memories, sessions, tool calls, success rate, and embedding coverage
Knowledge browser — filterable, sortable table of all memory entries with inline editing
Tool performance — per-tool success rates, error history, average duration
Upcoming and overdue — time-sensitive items due soon or past due
Conversation history — searchable archive of all past sessions with consolidation status
Superseded items — toggle to see fact history and how knowledge evolved over time

What you can do

Create new memory entries manually (stored with high confidence)
Edit any field on any memory entry — content, category, context, entity, sensitivity
Delete entries the agent got wrong
Toggle sensitive to hide or show private data
Search across all knowledge using hybrid semantic+keyword search
Filter by category, context, or entity

Maintenance actions

The dashboard also provides maintenance tools for keeping your memory healthy:

Consolidate — distill old conversation sessions into durable knowledge notes
Rebuild Embeddings — re-embed all knowledge items and rebuild the search index
Reconcile — scan for contradictory facts across sessions and resolve them automatically

To launch the Agent UI with the dashboard: gaia chat --ui

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 once per session start, 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 failed tool call is stored as an error pattern; the next session’s system prompt includes a “Known errors to avoid” list so the agent doesn’t repeat it.
Session consolidation — conversations older than 14 days are distilled into durable notes (extracted facts live indefinitely; raw conversations are pruned at 90 days), 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:

gaia memory bootstrap --reset

To completely delete all memory, remove the database file:

rm ~/.gaia/memory.db

CLI Reference

Command	Description
`gaia memory bootstrap`	Run full onboarding (conversation + discovery)
`gaia memory bootstrap --chat-only`	Conversational onboarding only
`gaia memory bootstrap --discover`	System discovery scan only
`gaia memory bootstrap --infer`	LLM-assisted profile inference from browser history and installed apps
`gaia memory bootstrap --reset`	Delete discovery items (with confirmation)
`gaia memory bootstrap --system`	Re-scan and refresh system context (OS, hardware, apps, versions)
`gaia memory bootstrap --reset-system`	Clear system context entries and optionally disable auto-collection
`gaia memory status`	Show memory stats (counts, categories, contexts, synthesized procedures)

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 Dashboard 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 Memory Dashboard for visual knowledge management

Agent SDK

Chat SDK for building conversational agents programmatically

Build Your First Agent

Create a custom agent with tools and memory in minutes

​Prerequisites

​Enable Memory

​Via the Agent UI (recommended)

​Via the API (for headless / scripted setups)

​Try It Right Now

​How It Works

​Quick Start

​Memory Tools

​remember

​recall

​update_memory

​forget

​search_past_conversations

​Your Second Brain

​Knowledge Categories

​Context Scoping

​Sensitive Data

​Entity Linking

​Temporal Awareness

​How reminders work

​Intelligent Extraction

​Memory Dashboard

​What you can see

​What you can do

​Maintenance actions

​How Memory Improves Over Time

​Procedural memory (skills)

​Privacy

100% Local

User Control

Bootstrap Consent

Sensitive Flagging

​Deleting all memory

​CLI Reference

​System context (versions, hardware, apps)

​Next Steps

Memory SDK Reference

Agent UI

Agent SDK

Build Your First Agent

Prerequisites

Enable Memory

Via the Agent UI (recommended)

Via the API (for headless / scripted setups)

Try It Right Now

How It Works

Quick Start

Memory Tools

remember

recall

update_memory

forget

search_past_conversations

Your Second Brain

Knowledge Categories

Context Scoping

Sensitive Data

Entity Linking

Temporal Awareness

How reminders work

Intelligent Extraction

Memory Dashboard

What you can see

What you can do

Maintenance actions

How Memory Improves Over Time

Procedural memory (skills)

Privacy

Deleting all memory

CLI Reference

System context (versions, hardware, apps)

Next Steps