Memory

Persistent memory in OpenWalrus — structured knowledge that evolves with your agents.

Memory in OpenWalrus is not chat history. It's a structured knowledge store — facts, preferences, and persona traits — that agents can read and write over time.

How memory works

Memory entries are key-value pairs with metadata:

Field	Description
`key`	Unique identifier
`value`	Content of the entry
`metadata`	Optional JSON metadata
`created_at`	When the entry was created
`accessed_at`	Last access time
`access_count`	Number of accesses
`embedding`	Optional vector embedding for semantic recall

Profile injection

Entries with user.* or soul.* key prefixes are treated as stable identity. These are always included in the system prompt — they define who the user is and how the agent should behave.

All other entries are retrieval-only. Agents access them through the recall tool.

Tools

Memory registers two tools via the hook system:

remember — store a new entry or update an existing one
recall — search entries by keyword or semantic similarity

Backends

OpenWalrus ships with three memory implementations:

InMemory

Volatile, HashMap-backed. Data is lost when the daemon stops. Good for testing.

SqliteMemory

Persistent SQLite database with FTS5 full-text search and optional vector recall. Stored at ~/.openwalrus/data/.

This is the default backend.

FsMemory

Filesystem-backed Markdown files at ~/.openwalrus/data/. Human-readable and editable — you can modify memory entries with a text editor.

Memory is not appended to chat history. Instead, the compile() method converts relevant entries into a system prompt section. This keeps the context window efficient — only profile entries and recently recalled knowledge appear in the prompt.

What's next

Hooks — how memory plugs into the agent lifecycle
Agents — agent configuration and execution
Configuration — directory structure and config file