#Memory

Sero Memory is a built-in plugin (@sero-ai/plugin-memory) that gives the agent durable context across sessions. It is meant for practical recall: preferences, project notes, identity/profile details, and daily work logs that help future conversations start with less repeated setup. See the Plugin Catalog for the built-in plugin inventory.

Treat memory as helpful context, not as perfect recall or a complete audit log.

#What memory stores

Memory stores markdown files in the active Sero profile's global workspace:

• MEMORY.md — durable facts, decisions, preferences, lessons learned
• IDENTITY.md — agent identity, behavior rules, communication style
• USER.md — user profile details such as role, stack, and preferences
• memory/daily/YYYY-MM-DD.md — append-only daily activity logs

Use synthetic, non-sensitive examples when testing memory. For example:

Remember that this demo project uses pnpm and prefers small focused PRs.

Avoid storing secrets, access tokens, private customer data, or anything you would not want included in local profile state or debug output.

#How memory appears in chat

Before an agent turn starts, the Memory plugin can add selected memory context to the agent's system prompt. This is selective, budgeted context — not every memory file and not every daily log is always included.

At a high level:

1. Core profile and long-term memory files can be included directly.
2. When search support is available, relevant older logs or transcript-derived entries may be retrieved and included.
3. Daily logs are not pasted wholesale into every turn.

When the renderer exposes memory context for a message, it may appear as a collapsed memory-context block in the chat UI. Use that as a debugging aid: it shows what context was attached to that turn, not everything Sero knows.

#Inspect and update memory

The agent can use bridged CLI tools to read, write, list, and search memory. You can ask for these in chat, or use the command-shaped examples below when working in a Sero session.

#List and read memory

sero memory list
sero memory read --target memory
sero memory read --target user

Useful targets include memory, identity, user, and daily.

#Add or update a durable note

sero memory write --target memory --content "Demo preference: keep release notes short and action-oriented."

By default, writes append. Overwriting managed memory files is possible through the tool, but should be used carefully because it replaces existing context.

#Search memory

For keyword-style search across memory files:

sero memory search --query "release notes"

For QMD-backed memory search, when available:

sero memory_search --query "how does this demo project handle releases" --mode keyword
sero memory_search --query "release process preferences" --mode semantic

memory_search supports keyword, semantic, and deeper hybrid search modes in the technical implementation, but semantic/deep behavior depends on QMD being available and indexed for the current profile.

#Slash commands

The Memory plugin registers these slash commands:

• /memory — ask the agent to list or manage memory with the memory tool
• /memory-log — show the memory plugin debug log path

Examples:

/memory list my memory files
/memory-log

Slash commands run through the current agent session.

#Where the data lives

Memory files live under the active profile's global workspace:

<SERO_HOME>/workspaces/global/MEMORY.md
<SERO_HOME>/workspaces/global/IDENTITY.md
<SERO_HOME>/workspaces/global/USER.md
<SERO_HOME>/workspaces/global/memory/daily/YYYY-MM-DD.md

Memory debug logs live under:

<SERO_HOME>/debug/memory/

<SERO_HOME> is profile-resolved. For the default profile it is usually ~/.sero-ui/, but custom profiles can use another root. For the canonical storage map, see State and Folders.

#Privacy and safety

Memory is local/profile-scoped Sero state, but it can still be sensitive:

• Memory context may be sent to whichever model/provider is handling a turn.
• Debug logs and screenshots can expose private facts if you include memory content in support reports.
• Profile folders can contain auth material, settings, workspaces, and app state; treat them as sensitive local data.
• Do not store passwords, API keys, recovery codes, financial data, or private third-party data in memory.

Before sharing logs or screenshots, redact names, paths, project details, credentials, and memory content that should remain private.

#Limits and troubleshooting

#Recall is selective

Memory helps the agent recover useful context, but it is not guaranteed to remember every fact. If something matters for the current task, mention it in the prompt or ask the agent to inspect memory first.

#QMD search may be unavailable

Core memory tools still work without QMD. If QMD is unavailable, semantic search and selective retrieval degrade; keyword search and direct reads are the safer fallbacks.

Try:

sero memory search --query "demo project"
sero memory read --target memory

#Choose live or frozen snapshots

Live mode reads the managed memory files again for each turn. Frozen mode takes one long-term memory snapshot for the session. Changes to those files do not enter the frozen context until you start another session.

sero memory config --snapshot live
sero memory config --snapshot frozen

#Session transcripts are searchable local files

Memory exports transcripts before a session switch, before a fork, and at shutdown. It also backfills earlier sessions in the background. The exports can contain user messages, assistant messages, and tool activity. They are stored under the active agent directory and can be returned by memory_search.

Use --scope sessions to search only transcript exports. Treat these files as private. They do not provide a complete or immutable audit log.

#Consolidation uses a model

Consolidation extracts durable entries from daily logs and writes them to MEMORY.md. It requires an active model. You can run it now or set a schedule:

sero memory consolidate
sero memory consolidate --schedule daily
sero memory consolidate --schedule weekly
sero memory consolidate --schedule off

Scheduled consolidation uses Scheduler state. Sero does not overwrite an unreadable Scheduler state file. Repair that file before you enable the job.

#Memory context may not be visible

The chat UI may show memory context as a collapsed block when available, but visibility is not the same as storage. If you do not see a memory block, use the tools to inspect stored memory directly.

#Updates can duplicate or go stale

Memory is markdown managed by tools and agent behavior. If a preference changes, ask the agent to update the old entry rather than append a contradictory one. For example:

Update memory: this demo project now uses npm instead of pnpm.

#More detail

This guide is the user-facing overview. For implementation details, context budgets, QMD integration, lifecycle hooks, and exact file behavior, see the source reference docs/features/memory.md on GitHub.