Agents and memory#

Each Roost agent has its own purpose, ongoing conversation, workspace, and Codex memory. Give agents clear responsibilities so you know where to return for a piece of work. You can assign focused work between them with delegation.

An agent's soul defines how it should behave: its purpose, voice, and boundaries. Memory holds context it has learned. Editing the soul changes its ongoing instructions; starting a schedule is a separate action.

Soul and memory settings#

Open an agent's settings from the conversation header:

• Soul edits .roost/agents/<agent-id>/SOUL.md. New souls start from the agent's purpose and a small OpenClaw-inspired template covering character, voice, boundaries, and continuity. The soul is loaded explicitly on every send; it does not depend on memory retrieval. Changes take effect next turn. Saved threads receive a developer update with thread/inject_items when the soul changes, since resume overrides alone do not replace existing messages.
• Agents can use roost_read_soul and roost_update_soul to evolve their own soul. These tools are bound to the current agent and thread and accept no filesystem path. Workspace files can be created and edited for the user's task. The agent is instructed to make targeted edits for explicit lasting requests, and propose inferred changes before applying them. These authorization rules are prompt instructions; ordinary scheduled runs are additionally blocked from soul mutation tools by the server. Periodic reflection has its own limited authorization, described below. Roost creates its own notice for every saved change, visible in both response styles. The Soul tab shows before/after history, source, reason, and Undo. Revision checks reject stale saves and undo attempts that would overwrite a newer change. Previous files also remain under soul-history/<revision>.md.
• Memory displays the agent's generated memory_summary.md and MEMORY.md when present. Native Codex memory generation and use are enabled. They are asynchronous and depend on Codex eligibility/idle-time rules; this is not instant recall after every reply. Roost's automation worker is separate from native memory generation.

Periodic reflection#

Each agent reflects every six hours by default while Roost is running. In Agent settings → Soul → Reflection, choose hourly, every six hours, daily, or Off. Reflect now queues one review immediately, including when periodic reflection is off. Existing agents receive the default on upgrade; the first check is six hours after their reflection settings are initialized.

Inspired by OpenClaw heartbeats, reflection runs through the durable worker, waits for busy agents, and stays quiet when nothing needs changing. It only runs after new non-reflection activity; downtime produces one catch-up rather than a backlog. User chats take priority over queued reflections. Changing the interval or switching Off cancels queued periodic reflections; an active reflection may finish. Each reflection has a two-minute timeout and a record in Automations → Run history. Failures are visible, and interrupted work is not replayed immediately.

Reflection reviews a bounded copy of the agent's recent visible conversation and its own native memory in a fresh thread. It can make small, evidence-backed improvements to voice, judgment, and working style without asking again. It must preserve purpose, boundaries, explicit instructions, and changes the user undid; personal facts and task history belong in memory. The Soul tab identifies edits as Reflection, with the reason, before/after text, and Undo. Actual soul writes always create a conversation notice, even if the final reply is quiet.

Reflection exposes only soul read/update tools. Its native sandbox is read-only, with approvals, connected apps, web search, and network access disabled. It cannot use Roost's computer, delegation, scheduling, notification, or dashboard tools. This does not change the host-level isolation limits described below.

Native Codex memory consolidation remains separate: reflection reads memory but does not rewrite generated memory files or force a consolidation. OpenClaw also distinguishes heartbeats from memory consolidation.

What stays separate#

Each agent has a separate .roost/agents/<agent-id>/codex home. Roost sets both CODEX_HOME and CODEX_SQLITE_HOME, and pins sqlite_home so an inherited setting cannot send its database writes to the host. Sessions, memory files, and memory SQLite state stay there. Host memory, personal AGENTS.md, hooks, skills, and MCP server configuration are not copied. Project instruction discovery is disabled; the soul supplies the agent's instructions explicitly.

The operating-system user's Codex login is shared intentionally. Roost requires file-based login credentials; for keyring-only setups run codex login -c cli_auth_credentials_store='"file"'. With ChatGPT login, the host owns refresh-token rotation and passes access tokens to isolated app-servers using chatgptAuthTokens. Refresh tokens are not copied into agent homes. First-party connected apps retain the host's app enablement/permission settings; third-party MCP servers and plugins are not automatically imported.

Existing conversations migrate lazily on the next send. Their original rollouts remain untouched. Roost archives displayable history in its database and gives the new private thread up to 32,000 characters of recent user/assistant text for continuity. Prior developer instructions, reasoning, and tool payloads are not injected into the new session. Old shared memories are not imported, and copies of legacy sessions already in the host's memory store are not deleted.

This is a memory and session storage boundary, not an OS security boundary: read-only filesystem tools can still access files allowed by the host sandbox, and connected apps use the same user's account. Roost instructs agents not to read other agents' or host memory stores. Strong adversarial isolation would require separate OS users/containers and connector credentials.

Data and backups#

Paths above are relative to the data directory (.roost for a source checkout). The installed service uses ~/.local/share/roost/data by default. Back up the whole data directory to retain conversations, uploads, downloads, souls, and Codex memory together. See Install and operate Roost for updates and recovery.

Shared note#

The Note view is a persistent user-visible document for each agent, separate from soul, private memory, and message threads. Its maintenance instructions guide note upkeep without authorizing external actions. See Shared agent note for editing, autosave, revisions, and recovery.