Memory
How CompozyOS stores durable Markdown memory across profile, workspace, and agent scopes, gates dreaming runs, and routes every write through the controller.
Memory is disabled by default. CompozyOS is a control plane: persistent knowledge and background
consolidation are explicit choices. To enable memory, set memory.enabled = true in the daemon's
config.toml and restart. Dreaming remains off until roles.dream.enabled = true is also set.
Existing explicit settings and stored memory are preserved.
You can browse existing memories in Knowledge, the Command Palette, or the memory API/CLI while automatic memory is disabled. An empty workspace shows an empty catalog. If storage is unavailable, Knowledge displays an error and does not automatically retry the failed list request.
Memory is the durable layer that survives a session. CompozyOS stores curated facts as Markdown files behind typed indexes so agents can rediscover knowledge without replaying past transcripts. The runtime keeps three scopes — profile, workspace, and agent — and a dreaming loop that promotes recall-validated signal into curated memory.
Use this section when an agent should carry durable project knowledge across sessions, when a workspace needs facts that should not live in a prompt, or when the controller, dreaming, or the extractor changed a memory file and you need to understand why. Memory is not a transcript archive. It is a curated working set: small enough for agents to read, typed enough to inspect, and scoped enough that one project does not leak into another.
Session pressure compaction remains independently controlled by session.compaction.enabled.
It reuses checkpoint coverage and may launch a summary child when an active session reaches the
pressure threshold, even with persistent memory disabled. Idle sessions and session-end memory
updates do not start that work. An explicit checkpoint-role opt-out or a failed summary leaves
uncovered events unarchived.
In this section
Memory system
Use this page for storage layout, prompt injection, the controller WAL, and the CLI/API surfaces that read or mutate memory.
Profile, workspace, and agent memory
Use this page when you need scope resolution rules, agent-tier selection, and where each kind of memory lives on disk.
Dreaming and promotion gates
Use this page to understand the dreaming loop, recall-signal gates, and what `compozy memory dream trigger` actually does.
Memory best practices
Use this page when authoring memories: keep them small, durable, and verifiable.
Background role status reflects the daemon memory master switch as well as effective role settings. Pressure compaction still uses session.compaction.enabled and the checkpoint role switch independently. An interrupted extractor stream is a failure even when its partial text looks like valid JSON; the diagnostic retains that text without admitting it as a candidate.