Building an Offline-First Memory for Your AI Agent

I’ve often felt the frustration of digging through old project notes to remember why I made a specific technical choice. It is a common pain for developers: we write things down, but we can’t find them when we need them. AI agents face the same struggle. They need a way to remember facts without getting lost in a sea of text or hitting token limits.

I want to share an approach for an offline-first memory architecture. It keeps Markdown as your source of truth while adding a derived index for fast search.

What You’ll Need

• OpenClaw workspace (default ~/.openclaw/workspace).
• Markdown files for storage.
• SQLite with FTS5 support.
• Git for durability and auditing.

Quick Start

You can set up a basic memory system in about five minutes by following these steps.

1. Organize your workspace: Set up a directory structure that separates daily logs from stable facts.

   ~/.openclaw/workspace/
     memory.md                    # durable facts + preferences
     memory/
       YYYY-MM-DD.md              # daily logs
     bank/                        # stable memory pages
       world.md                   # objective facts
       experience.md              # agent history
       opinions.md                # subjective judgments
       entities/                  # information about specific people or projects

2. Log your daily progress: Write your notes in the memory/ folder. Use a narrative style that makes sense on its own.

3. Tag facts for retention: At the end of your log, add a ## Retain section. Use prefixes to help the system categorize facts.

   • W: World facts
   • B: Biographical/Experience
   • O: Opinions (with optional confidence like O(c=0.95))
   • S: Observations

   Example:

   ## Retain
   - W @Peter: Currently in Marrakech (Nov 27–Dec 1, 2025) for Andy’s birthday.
   - B @warelay: I fixed the Baileys WS crash by wrapping connection.update handlers in try/catch (see memory/2025-11-27.md).
   - O(c=0.95) @Peter: Prefers concise replies (<1500 chars) on WhatsApp.

4. Query your memory: Use the CLI to find specific information from your derived SQLite index.

   openclaw memory recall "search term" --k 25 --since 30d
   openclaw memory reflect --since 7d

Troubleshooting

• Retrieval is weak or inaccurate: If simple text search isn’t finding what you need, ensure your ## Retain bullets are self-contained and narrative. You can also add an optional embeddings table to your SQLite index for semantic recall.
• Search becomes slow as the corpus grows: If you have tens of thousands of chunks and brute-force search lags, you can switch to an HNSW index or explore SuCo (Subspace Collision) for better latency.

AI Setup Assistant

What’s Next

• Workspace Memory v2 Research Notes
• CLI Integration Guide