How to Configure Memory
🔧 Tools · 📋 Prompt
The agent can maintain persistent memory across conversations. When it learns something worth remembering (user preferences, project context, recurring corrections), it saves a concise fact via the save_memory tool. On the next session, saved memories are loaded into the system prompt automatically, either all of them or only the most recent (see Memory Context Strategy).
Memory Tools
The tools come from the writable store. Which ones the agent gets depends on what that store supports:
| Tool | Purpose | Stores |
|---|---|---|
save_memory | Save a new fact | All |
update_memory | Replace a saved memory by its id | All except tag_notes |
read_memory | Read a memory's full content by its id | searchable_memory_notes |
search_memory | Search saved memories by relevance (knn, keyword, or mixed, the default) | searchable_memory_notes |
List and Enable Stores
za agents capabilities memory-stores list
za agents capabilities memory-stores configure <store-name>
Configure Provider Settings
za agents capabilities memory-stores settings
| Setting | Type | Default | Description |
|---|---|---|---|
inject_context | bool | true | Load saved memories into the system prompt each turn |
memory_context_strategy | str | "full" | How saved memories are loaded into the prompt: "full" or "recent" (see Memory Context Strategy) |
provide_tools | bool | true | Expose the writable store's memory tools to the agent |
writable_source | str or null | null | Which store to write to (e.g. "tag_notes", "memory_notes", "searchable_memory_notes", "file", "in_memory"); when null, the first enabled store |
read_instructions | str or null | null | Override the default memory injection preamble |
write_instructions | str or null | null | Append domain-specific policy for when/how the agent should save (see Custom Memory Policy) |
Memory Stores
| Store | CLI name | Default | Description |
|---|---|---|---|
| Tag Notes | tag-notes | disabled | Production: memories stored per user in the platform |
| Memory Notes | memory-notes | disabled | Platform-managed notes with scope filtering |
| Searchable Memory Notes | searchable-memory-notes | disabled | Platform-managed notes the agent can search and cite |
| File | file | disabled | Development: JSON file on disk |
| In-Memory | in-memory | disabled | Testing only: lost on restart |
Tag Notes
Stores memories as notes attached to a platform tag. Best for production deployments: memories are per user and persist across sessions.
za agents capabilities memory-stores configure tag-notes
Configuration
| Setting | Type | Default | Description |
|---|---|---|---|
tag_id | str or null | null | Specific tag to attach memories to; when null, uses the user's favorites tag |
use_favorites | bool | false | Use the user's favorites tag as the memory store |
Memory Notes
Platform-managed memory notes with scope-based access control. Multiple scopes allow separating personal notes from shared ones.
za agents capabilities memory-stores configure memory-notes
Configuration
| Setting | Type | Default | Description |
|---|---|---|---|
include_scopes | list[str] | ["own"] | Which scopes to read from: "own", "shared_with_me" |
Searchable Memory Notes
Memory notes backed by the search index. On top of save_memory and update_memory, the agent gets search_memory and read_memory, so it can find memories that were not preloaded into the prompt. Search results are snippets; read_memory returns the full content. Each memory carries a source_url (/notes/{id}), which makes it citable.
za agents capabilities memory-stores configure searchable-memory-notes
Configured under searchable_memory_note_memory_store_configuration:
| Setting | Type | Default | Description |
|---|---|---|---|
enabled | bool | false | Enable the store |
include_scopes | list[str] | ["own"] | Which scopes to read from: "own", "shared_with_me" |
max_preloaded_memories | int | 100 | Most recent memories loaded into the prompt under the full strategy |
frontmatter_enabled | bool | true | Record the chats a memory was created and edited from in a YAML frontmatter block (memory_origins); the agent never sees it |
search_id_field | str | "custom_metadata.metadata.identifier" | Index field holding the memory id |
search_snippet_field | str | "highlight" | Index field returned as the search snippet |
search_created_at_field | str | "custom_metadata.metadata.created" | Index field holding the creation date |
File
Stores memories in a JSON file on disk. Useful during development: memories survive restarts but aren't tied to a platform user.
za agents capabilities memory-stores configure file
Configuration
| Setting | Type | Default | Description |
|---|---|---|---|
file_path | str or null | null | Path to the JSON file; when null, uses a default location |
In-Memory
Holds memories in process memory. Lost on restart, so useful only for testing.
za agents capabilities memory-stores configure in-memory
No additional configuration beyond enabled.
Memory Context Strategy
memory_context_strategy picks how saved memories enter the system prompt when inject_context is true:
| Strategy | Behaviour |
|---|---|
full | Loads every memory each store returns. searchable_memory_notes caps this at max_preloaded_memories. |
recent | Loads the most recent memories per store, sized by recent_memory_context_strategy_configuration.size (default 10). When more are saved, the prompt says how many are hidden and, with a searchable store, tells the agent to search before assuming it doesn't know. tag_notes does not support it. |
{
"memory_provider_configuration": {
"enabled": true,
"memory_context_strategy": "recent"
},
"recent_memory_context_strategy_configuration": {"size": 20}
}
Memory Citations
To have the agent cite the memories its answer relies on, add memories to the citable resources of the citation instructions:
{
"citation_instruction_source_configuration": {
"enabled": true,
"citable_resources": ["search_results", "memories"]
}
}
The agent cites recalled memories and search_memory results in the [[N]](source_url "extract") form. Only searchable_memory_notes gives memories a source_url.
What the Agent Remembers
The agent applies a signal gate: it only saves facts genuinely valuable for future sessions:
- User identity and role
- Stated preferences ("I prefer bullet-point answers")
- Corrections and recurring conventions
- Project decisions
It skips transient task progress, raw data, and information the user wouldn't want persisted.
Custom Memory Policy
Add domain-specific guidance via the write_instructions setting:
za agents capabilities memory-stores settings
When prompted for write_instructions, provide your policy:
Never save credentials or API keys. Summarize project decisions concisely. When in doubt, ask the user before saving.