/* TL;DR */

ClawdBrain replaces flat memory files with a structured SQLite database — 7 table types, FTS5 full-text search in 36ms, and automated reflection cycles that turn raw session data into searchable long-term memory. 204KB, one dependency, zero API costs.

AI agents have an amnesia problem. Every session starts from scratch. The agent that helped you debug a gnarly race condition yesterday? It has no idea who you are today. Your preferences, your project structure, the lessons it learned — all gone. Most platforms work around this with flat memory files. OpenClaw has MEMORY.md and SOUL.md — workspace files injected into every API call. They work, but they don't scale. Ours hit 29KB before we noticed. That's 29KB of unstructured text the agent has to parse every single turn, with no way to search, query, or selectively load what's relevant. ClawdBrain is our answer: a structured SQLite database that gives agents real long-term memory.

The Architecture

ClawdBrain is deliberately simple. One SQLite database, one CLI tool, one npm dependency (better-sqlite3). No cloud services, no vector embeddings, no API costs.

clawdbrain/
├── bin/clawdbrain.js    # CLI interface
├── lib/db.js           # Database module + schema
└── ~/.openclaw/clawdbrain.db  # The actual brain (204KB)

The database uses SQLite's FTS5 extension for full-text search. Every table has an FTS5 virtual table kept in sync via triggers. A search across all memory types completes in about 36 milliseconds.

Seven Types of Memory

We landed on seven tables after experimenting with what agents actually need to remember:

Facts

Knowledge stored as subject-predicate-object triples with confidence scores. This is the workhorse — 103 of our 134 memories are facts.

bash
clawdbrain add-fact "gateway" "runs_on" "Mac Mini M4" --confidence 0.95 --category system
clawdbrain add-fact "user" "prefers" "direct communication" --confidence 0.9 --category preference

Facts can be superseded (when knowledge changes) and have optional expiration dates. Confidence scores let the agent weigh how certain it is about a piece of knowledge.

Episodes

Session diary entries — what happened, what decisions were made, what lessons were learned. Each episode has a mood, importance level, and structured arrays for decisions and lessons.

bash
clawdbrain log "Shipped v0.2.0 with error tracking" --importance high --mood productive --tags release,milestone

Episodes are the narrative thread. They answer "what happened last Tuesday?" in a way session logs never could.

Procedures

Step-by-step workflows the agent has learned. Each procedure tracks its steps, known gotchas, prerequisites, and success rate. When the agent encounters a familiar task, it can pull up the procedure instead of figuring it out from scratch.

Insights

Meta-observations about patterns. These are higher-order than facts — they're conclusions drawn from experience. Examples from our database: - "User wants autonomy at night but direct control during the day" - "Only use LLMs for code, reasoning, and content generation — replace everything else with deterministic scripts" - "Pipeline is maturing — 20 articles in one day with zero manual intervention"

Errors

An auto-deduplicating error tracker. When the same error type hits the same agent, ClawdBrain increments the occurrence count instead of creating a new entry. This surfaces chronic problems without spamming the database.

bash
clawdbrain log-error "JSON parse failure in article pipeline" --type parse_error --agent editor
# Second occurrence? Increments count, updates last_seen. No duplicate.

Projects and Entities

Lighter-weight tables for tracking active work (projects with status, priority, blockers) and the people/agents/services the system interacts with.

Automated Reflection

The most interesting feature isn't the database — it's how it gets populated. A cron job runs three times daily and does something unusual: it makes the agent reflect on its own recent activity. The reflection cycle: 1. Read the last few session logs 2. Review recent git activity across all repos 3. Check the current system state 4. Store structured memories — turning raw experience into searchable knowledge 5. Identify up to 2 improvement suggestions and file them as GitHub issues This is the agent equivalent of journaling. Instead of hoping important information sticks in flat files, the agent actively processes what happened and decides what's worth remembering.

Why SQLite, Not a Vector Database

The default answer for "AI memory" in 2026 is a vector database with embeddings. We went the other direction. FTS5 is fast enough. Full-text search across all tables in 36ms. For an agent that needs to recall knowledge mid-conversation, that's effectively instant. No external dependencies. No Pinecone API costs, no embedding model to run, no network latency. The entire brain is a 204KB file on disk. Portable and backable. Daily backups to Google Drive are trivial — it's one file. Restoring the agent's entire memory is a single file copy. Structure over similarity. Vector search is great for "find me something semantically similar to this query." But agent memory is more often "what do I know about this specific topic?" FTS5 handles that directly. We're planning to add vector embeddings later as an optional layer for semantic search. But the structured foundation comes first.

What We've Learned After 134 Memories

ClawdBrain has been running for five days. Some early observations: Facts dominate. 77% of stored memories are facts. Agents accumulate system knowledge fast — config values, user preferences, architectural decisions. The subject-predicate-object format maps naturally to how agents think about their environment. Deduplication matters. Without guardrails, the reflection cycle stores the same fact multiple times in slightly different wording. We're working on dedup detection at insert time. Confidence is useful but underused. Most facts get stored at 0.8-1.0 confidence. We need confidence decay — facts should lose certainty over time unless reinforced by new evidence. Episodes need curation. Three reflection cycles per day generates ~3 episodes daily. After a month that's ~90 episodes. Without summarization or consolidation, the episode table will grow faster than it's useful to query.

What's Next

Dashboard integration. Browse the agent's memories from the web UI — search, filter by type, see the knowledge graph. Auto-logging. Episodes created automatically at the end of each agent session, not just during reflection cycles. Context window loading. The end game: when 1M+ token context windows get cheap enough, load relevant ClawdBrain memories at session start. The agent would begin every conversation with full recall of everything it's learned. Confidence decay. Facts lose certainty over time unless reinforced. "The gateway runs on a Mac Mini M4" should stay high confidence. "The dashboard port is 3141" should be re-verified periodically. Cross-agent memory. Right now only the main agent writes to ClawdBrain. Sub-agents should be able to query it for context and contribute their own observations.

The Bottom Line

AI agents don't need bigger context windows to have better memory. They need structured storage with fast search and automated reflection. ClawdBrain is 204KB of SQLite doing the job that 29KB of flat files couldn't. 134 memories in five days. Growing at about 27 per day. One dependency, 36ms search, zero API costs. Sometimes the boring technology is the right technology.