clawdbot/docs/concepts/memory.md

summary, read_when

summary	read_when
How Clawdbot memory works (workspace files + automatic memory flush)	You want the memory file layout and workflow You want to tune the automatic pre-compaction memory flush

Memory

Clawdbot memory is plain Markdown in the agent workspace. The files are the source of truth; the model only "remembers" what gets written to disk.

Memory files (Markdown)

The default workspace layout uses two memory layers:

• memory/YYYY-MM-DD.md
  • Daily log (append-only).
  • Read today + yesterday at session start.
• MEMORY.md (optional)
  • Curated long-term memory.
  • Only load in the main, private session (never in group contexts).

These files live under the workspace (agents.defaults.workspace, default ~/clawd). See Agent workspace for the full layout.

When to write memory

• Decisions, preferences, and durable facts go to MEMORY.md.
• Day-to-day notes and running context go to memory/YYYY-MM-DD.md.
• If someone says "remember this," write it down (do not keep it in RAM).

Automatic memory flush (pre-compaction ping)

When a session is close to auto-compaction, Clawdbot triggers a silent, agentic turn that reminds the model to write durable memory before the context is compacted. The default prompts explicitly say the model may reply, but usually NO_REPLY is the correct response so the user never sees this turn.

This is controlled by agents.defaults.compaction.memoryFlush:

{
  agents: {
    defaults: {
      compaction: {
        reserveTokensFloor: 20000,
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 4000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store."
        }
      }
    }
  }
}

Details:

• Soft threshold: flush triggers when the session token estimate crosses contextWindow - reserveTokensFloor - softThresholdTokens.
• Silent by default: prompts include NO_REPLY so nothing is delivered.
• Two prompts: a user prompt plus a system prompt append the reminder.
• One flush per compaction cycle (tracked in sessions.json).
• Workspace must be writable: if the session runs sandboxed with workspaceAccess: "ro" or "none", the flush is skipped.

For the full compaction lifecycle, see Session management + compaction.

Vector memory search

Clawdbot can build a small vector index over MEMORY.md and memory/*.md so semantic queries can find related notes even when wording differs.

Defaults:

• Enabled by default.
• Watches memory files for changes (debounced).
• Uses remote embeddings (OpenAI) unless configured for local.
• Local mode uses node-llama-cpp and may require pnpm approve-builds.

Config example:

agents: {
  defaults: {
    memorySearch: {
      provider: "openai",
      model: "text-embedding-3-small",
      fallback: "openai",
      sync: { watch: true }
    }
  }
}

Tools:

• memory_search — returns snippets with file + line ranges.
• memory_get — read memory file content by path.

Local mode:

• Set agents.defaults.memorySearch.provider = "local".
• Provide agents.defaults.memorySearch.local.modelPath (GGUF or hf: URI).
• Optional: set agents.defaults.memorySearch.fallback = "none" to avoid remote fallback.