Skip to main content

Memory & Sessions

Global Agent Identity​

A single .agent/IDENTITY.md file defines the agent's persona, tone, and base posture for every project and conversation -- it is the first block of the system prompt.

  • Edit it to rebrand the assistant.
  • Delete it and the runtime regenerates a sensible default on next start.
  • No environment variable, fixed path; read-only hosts (containers) fall back to the built-in default instead of failing to boot.

User Preference Memory​

The agent keeps a small, durable profile of how you like to be helped (preferences, communication style, expectations, workflow habits) in a single .agent/USER.md file, rendered into the system prompt right after the Identity.

  • The agent maintains the file itself during chats via an inline memory tool (add / replace / remove / consolidate). It reconciles rather than just appends: a newer explicit preference supersedes a conflicting older one, so mutually exclusive preferences (like your default answer language) stay a single line instead of piling up.
  • A deterministic filter blocks secrets and sensitive personal data from ever being stored, and the file is kept small (USER_CHAR_LIMIT, default 1375).
  • Each session reads a frozen snapshot taken at session start, so prompts stay cache-stable and consistent across reloads; anything learned mid-session takes effect from your next session.

On by default; set USER_PROFILE_ENABLED=false to turn it off. Fixed path; read-only hosts fall back to a built-in default.

note

Temporary Chat never reads or writes this profile, so throwaway conversations do not shape personalization.

Background reconciliation (optional)​

Let the memory maintain itself. When enabled, a background pass periodically distills your recent conversation and reconciles the whole profile -- merging duplicates, resolving contradictions, dropping reversed or outdated preferences, and integrating new ones -- so it never drifts into a pile of conflicting lines.

USER_MEMORY_EXTRACTION=true            # default: false (off, byte-for-byte prior behavior)
USER_MEMORY_EXTRACTION_MODEL=          # empty = your session's model; pick a small/cheap one
USER_MEMORY_EXTRACTION_EVERY_N_TURNS=4 # run at most once every N new user turns
  • Requires USER_PROFILE_ENABLED=true. Runs in the background and never blocks or delays your message.
  • Uses the same safety as the inline tool (secret/PII filter, size cap, and a backup of the previous file); an empty or unchanged result never wipes or needlessly rewrites your memory.
  • Temporary Chat and demo mode never trigger it. Changes take effect from your next session (the running session keeps its frozen snapshot).

Session management​

Conversations are saved as JSON files on your machine. You can save, search, organize into folders, pin, archive, fork, and rename them.

  • Assign a color from a preset palette (on create, or later via the folder menu)
  • Reorder folders by drag-and-drop
  • Folders are collapsed by default, with open/closed state remembered per device
  • The folder list self-heals if its saved color/order values are ever corrupted

Auto chat titles (optional)​

Set SESSION_TITLE_MODE=llm and a new chat is named by a short LLM summary of your opening exchange instead of the first message's leading text.

SESSION_TITLE_MODE=llm        # default: truncate (previous behavior, byte-for-byte)
SESSION_TITLE_MODEL=          # empty = your session's model; pick a small/cheap one
  • The chat appears in the sidebar the instant you send (with a spinner while the title generates) and updates in real time when ready -- pushed over a WebSocket, no reload.
  • Generation runs in the background and never blocks or delays your message; on any failure the simple truncated title remains.