105 lines
3.4 KiB
Markdown
105 lines
3.4 KiB
Markdown
---
|
|
summary: "How Clawdbot memory works (workspace files + automatic memory flush)"
|
|
read_when:
|
|
- 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](/concepts/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`:
|
|
|
|
```json5
|
|
{
|
|
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](/reference/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:
|
|
|
|
```json5
|
|
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.
|