OpenClaw File-Backed Memory Notes for Durable Agent Knowledge

Why File-Backed Notes?

OpenClaw’s memory system stores agent knowledge as Markdown files in a dedicated notes directory. Unlike in-memory state that vanishes with each container restart, these files persist on the host filesystem through Docker volume mounts.

This design gives you:

• Human-readable memory — notes are plain Markdown you can read and edit
• Git-friendly — version control your agent’s knowledge base
• Portable — move notes between OpenClaw instances
• Inspectable — debug agent behavior by reading what it remembers

The Notes Directory

Memory notes live at:

/home/node/.openclaw/memory/notes/    (inside container)
/home/azureuser/.openclaw/memory/notes/  (on host via volume mount)

The directory structure:

~/.openclaw/
├── memory/
│   ├── main.sqlite          ← Embedding index
│   └── notes/               ← Markdown knowledge files
│       ├── seed.md
│       ├── durable.md
│       └── 2026-02-25.md    ← Auto-generated by memory flush
├── openclaw.json
└── ...

Creating Seed Notes

Seed notes provide initial knowledge for a fresh agent deployment. Create them before the agent runs its first conversation:

cat > ~/.openclaw/memory/notes/seed.md <<'EOF'
# Seed note
This is a test note to initialize file-backed memory/search.
EOF

After creating seed notes, restart the gateway so the memory search system indexes them:

docker compose restart openclaw-gateway

Practical Seed Notes

For a production deployment, seed notes can encode domain knowledge:

cat > ~/.openclaw/memory/notes/project-context.md <<'EOF'
# Project Context

## Infrastructure
- Running OpenClaw v2026.2.25 on Azure B2s VM (vm-openclaw-01)
- Docker Compose deployment with gateway on port 18789
- Control UI on port 18790
- Discord channel integration active

## Preferences
- Responses should be concise and technical
- Code examples use bash and Docker Compose
- Timezone: UTC for all timestamps

## Key Contacts
- Admin: azureuser (SSH access)
- Discord: configured via channels.discord
EOF

cat > ~/.openclaw/memory/notes/troubleshooting-log.md <<'EOF'
# Troubleshooting Log

## Known Issues
- Discord Error 4014: Requires Message Content Intent in Developer Portal
- Config migration: Use channels.discord path (not root discord key)
- SQLite permissions: chown 1000:1000 on memory directory
- Startup takes 8-12 seconds on B2s VM

## Resolution History
(Agent will append entries here during memory flush)
EOF

How Memory Flush Writes Notes

When configured (see the memory flush article), the agent automatically writes notes before context compaction. The typical flow:

1. Conversation approaches token limit
2. Memory flush fires with your configured prompt
3. Agent writes to memory/YYYY-MM-DD.md (or whatever path you specify)
4. Context is compacted
5. On the next query, memory search can retrieve the saved notes

Auto-Generated Note Example

After a flush, you might find:

# Session Notes — 2026-02-25

## Key Decisions
- Configured hybrid memory search with 70/30 vector/text split
- Set soft threshold to 4000 tokens for compaction flush
- Using all-MiniLM-L6-v2 for local embeddings

## Open Tasks
- Monitor embedding cache size after extended use
- Test memory recall accuracy across long conversations

Verifying Notes Inside the Container

Check that the gateway can see your notes:

docker exec -it openclaw-openclaw-gateway-1 sh -lc \
  'ls -la /home/node/.openclaw/memory/notes'

Expected output:

total 12
drwx------  2 node node 4096 Feb 25 23:37 .
drwx------  3 node node 4096 Feb 25 23:37 ..
-rw-r--r--  1 node node   68 Feb 25 23:37 seed.md

Organizing Notes

By Date (Recommended for Auto-Generated)

notes/
├── 2026-02-24.md
├── 2026-02-25.md
└── 2026-02-26.md

By Topic (Recommended for Seed Notes)

notes/
├── project-context.md
├── troubleshooting-log.md
├── user-preferences.md
└── architecture-decisions.md

Hybrid Approach

notes/
├── _seed/                    ← Manual seed notes (prefixed)
│   ├── project-context.md
│   └── known-issues.md
├── 2026-02-24.md             ← Auto-generated daily notes
├── 2026-02-25.md
└── 2026-02-26.md

Integration with Memory Search

When you configure memorySearch with the local provider, notes are automatically indexed:

1. Indexing: The gateway reads all .md files from the notes directory
2. Embedding: Each note is split into chunks and embedded using all-MiniLM-L6-v2
3. Storage: Embeddings are stored in main.sqlite
4. Query: When the agent searches memory, both vector and text search scan the index

Reindexing After Manual Changes

If you manually add or edit notes, trigger a reindex:

docker compose run --rm openclaw-cli memory reindex

Note Format Best Practices

Use Clear Headers

Headers help both humans and the search system understand note structure:

# Topic: Database Configuration

## Decision
Chose PostgreSQL over MySQL for the primary database.

## Rationale
- Better JSON support
- ACID compliance
- Team familiarity

Keep Notes Focused

One topic per note performs better in search than a single monolithic file. The embedding model (MiniLM-L6-v2) has a 256-token sequence limit — shorter, focused notes produce better embeddings.

Include Keywords

While vector search understands semantics, explicit keywords help the text search component:

# Keywords: docker, permissions, UID, chown, node user
# Topic: Container Permission Fix

The memory directory requires UID 1000 ownership...

Use Bullet Points for Facts

Facts stored as bullet points are easier for the agent to extract during retrieval:

## Server Details
- VM: vm-openclaw-01
- Region: East US
- Size: Standard_B2s
- OS: Ubuntu 24.04 LTS
- Docker: 28.4.0

Backup and Versioning

Git-based Versioning

Since notes are plain Markdown, track them with git:

cd ~/.openclaw/memory/notes
git init
git add .
git commit -m "Initial seed notes"

# After agent generates new notes
git add .
git commit -m "Session notes $(date +%Y-%m-%d)"

Automated Backup Cron

# Add to crontab
0 2 * * * tar czf /backup/openclaw-notes-$(date +\%Y\%m\%d).tar.gz \
  /home/azureuser/.openclaw/memory/notes/

Troubleshooting

Notes not found by search:

• Run memory reindex after adding new files
• Check file permissions (must be readable by UID 1000)
• Verify files have .md extension

Agent writes to wrong path:

• Check the memoryFlush.prompt — ensure the path template matches your directory structure
• The memory/YYYY-MM-DD.md path in the prompt is relative to the OpenClaw state directory

Notes disappear after restart:

• Verify the Docker volume mount includes the memory directory
• Check that Docker Compose doesn’t use an anonymous volume that gets recreated

Series Navigation

• Previous: OpenClaw SQLite Memory Store Bootstrap and Permissions
• Next: OpenClaw CLI Command Reference and Power Tips
• Series index: What is OpenClaw AI Agent Gateway?