Memory Tool
Persistent key-value storage backed by SQLite for cross-session recall.
Overview
The memory tool provides persistent key-value storage backed by SQLite. Data survives across sessions, allowing agents to remember facts, user preferences, project context, and past decisions. Memories can be organized with categories and searched by keyword.
By default, the database is stored at ~/.cagent/memory/<config-name>/memory.db, where <config-name> is derived from the loaded configuration (typically the YAML file name) and falls back to default when unavailable. When the agent is loaded from an OCI reference (e.g. docker/my-agent:latest), characters that are reserved in filesystem paths (such as :) are sanitised in the <config-name> segment — the agent's display name elsewhere is unchanged. Agents declared in the same configuration share this database by default; set an explicit path per toolset to isolate them.
Available Tools
| Tool | Description |
|---|---|
add_memory | Store a new memory with optional category |
get_memories | Retrieve all stored memories |
delete_memory | Delete a specific memory by ID |
search_memories | Search memories by keywords and/or category (more efficient than get_memories) |
update_memory | Update an existing memory's content and/or category by ID |
Configuration
toolsets:
- type: memoryOptions
| Property | Type | Default | Description |
|---|---|---|---|
path | string | ~/.cagent/memory/<config-name>/memory.db | Path to the SQLite database file |
Custom Database Path
toolsets:
- type: memory
path: ./agent_memory.dbCategories
Memories support an optional category field for organization and filtering. Common categories include:
preference— User preferences and settingsfact— Factual information about the project or userproject— Project-specific contextdecision— Past decisions and their rationale
TipMemory is especially useful for long-running assistants that need to recall information across conversations — like coding preferences, project conventions, or context discovered during previous sessions.