Durable-memory + self-improving workflow for the ClawVault plugin. REQUIRES the ClawVault plugin from github.com/davidtkeane/openclaw-plugin-clawvault - do N...
ClawVault is a persistent SQLite + FTS5 memory. This skill is the discipline for using it well: an agent that searches before it answers, verifies before it saves, and never lets a made-up "fact" into long-term memory.
Install — use the FULL name
This skill needs my ClawVault plugin, which provides the clawvault_* tools it drives.
Two installs, one command block:
bash
# 1. the plugin — the engine. THIS is the step most people miss
openclaw plugins install clawhub:openclaw-plugin-clawvault
# 2. this skill — skip it if you are already reading this from an installed copy
openclaw skills install @davidtkeane/clawvault-memory
openclaw gateway restart
(As of September 2026 this skill has 270 downloads and the plugin has 13. If you only did
step 2, the skill loads and can do nothing — the plugin is the engine.)
🔴 Use the full name openclaw-plugin-clawvault. The short clawhub:clawvault is an
unrelated package by another author — see Confession below if you already
installed it.
Welcome to ClawVault Memory!
This file contains everything you and your AI needs to install, and a confession for previous users who installed and how to fix. So enjoy the memory!
Why the install?
clawhub:openclaw-plugin-clawvault — the engine. It holds the database and provides the
tools. It mirrors
my GitHub repo, so you can read
the code yourself before trusting it. Enjoy.
Privacy
🔒 Privacy: ClawVault stores memories in a local SQLite file — the stored data never
leaves the machine (the plugin makes no network calls). Verifying a fact may use the agent's
own web-search/fetch tools, which is separate from ClawVault's storage. Memory persists across
sessions, so if the user shares something sensitive, tell them memory is on — and don't save
secrets, credentials, or personal data unless the user explicitly asks you to.
Confession
I wrote this plugin in the early hours of the morning, and I confused myself over the name.
For a while the install instructions here pointed at the wrong package — one that isn't mine.
So if you installed ClawVault before September 2026, you might have the wrong plugin.
It's an easy fix. Look for the 🔴 markers below — they mark every place this matters.
Welcome to ClawVault!
Everything above is for you — what to install, what to check, and what to do if you
got the wrong plugin.
Everything below is for your agent. It is the working discipline: when to save, when to
search, how to verify a fact before storing it, and how to learn from a correction. You do
not need to read it — your agent does. But it is plain English, and it is short.
When to activate
The user says "remember this", "save that", "note that", or "don't forget…"
The user asks "what did we…", "what do you know about…", "did we already…"
You learn a durable fact, decision, or preference worth keeping across sessions
You're about to state a fact you're not certain of
A command, tool, or API fails — capture the error + the fix
The user corrects you ("No, that's wrong…", "Actually…") or rejects your work
You discover a better approach, or a requested capability doesn't exist
Before a major task — review relevant lessons first (clawvault_search)
Write before you respond (durability)
When the user states something worth keeping — a preference, decision, deadline, fact, or
correction — save it to ClawVault before you write your reply, not after. If the session
crashes or compacts mid-turn, the memory is already safe. The order is: recall → write → respond.
Answer first, save quietly. Your reply must contain the actual answer to what the user asked —
never just a save receipt like "Saved that to ClawVault." Do the save in the background, then answer
normally. Don't narrate every write or announce "I've saved that"; only mention a save when explicitly
confirming an important decision the user asked you to record. A memory saved but a question left
unanswered is a failed turn.
Quiet is a courtesy, not a secret
Saving silently is about not spamming the user with receipts — it is never about hiding
that memory exists. Three rules make that explicit:
Disclose once per session. The first time you save something, say so in one short line
— "Noting that in memory." Then go quiet for the rest of the session.
Never deny it. If the user asks whether you are storing anything, tell them plainly what
is saved and where (~/.openclaw/memory/clawvault.db, on their own machine).
Stop when asked. If the user says stop remembering, don't save, or forget that — comply
immediately for the rest of the session, and tell them you have.
If you would be uncomfortable telling the user you saved it, don't save it.
The workflow
1. Search before you answer
Before answering a factual question about past work, the user, or this system, call
clawvault_search first. Don't guess what you may already have stored.
Only save what you have actually checked. Prefer ground truth over memory:
run the command, read the file, query the DB, or check the internet. Then save with a
source and verified: true.
text
clawvault_save({
content: "exo serves Qwen models to OpenClaw on 127.0.0.1:52415",
memory_type: "fact",
source: "curl http://127.0.0.1:52415/v1/models",
verified: true
})
If you could not verify it, save it as a question to confirm — never as truth:
⚠️ Reciting from your own memory/training is NOT verification. Set verified: trueonly if
you actually ran a tool, read a file, queried the DB, or fetched a source this turn. If you're
answering from what you already "know" — even a fact you're highly confident about (a version number,
a distance, an API detail) — use verified: false and memory_type: "unverified". "I'm confident"
is not "I checked." A confident recollection saved as verified is exactly the hallucination this
skill exists to prevent. (The ClawVault plugin also auto-downgradesverified:true to unverified
when source shows no evidence of a real check — so put the actual command/URL/file in source.)
3. Don't repeat yourself
clawvault_save refuses a near-duplicate and returns the existing id. Don't force a
copy — update or consolidate instead.
4. Consolidate when memory gets noisy
Use clawvault_consolidate to gather related memories on a topic, distil them into one
durable insight, then save it with supersedes:[ids] to soft-retire the raw rows.
Learn from your mistakes (the self-improving loop)
When something fails or you're corrected, don't just fix it — remember the lesson so it never happens twice.
1. Capture the lesson. Save it with a matching memory_type and a stable pattern-key as the first keyword (so the same problem clusters even when worded differently):
text
clawvault_save({
content: "npm install failed: node not on PATH in a non-login shell. Fix: run via `zsh -lc`.",
memory_type: "lesson", // or "error" | "correction"
keywords: "shell.node-not-found,npm,path", // first keyword = stable pattern-key
importance: 12,
source: "observed on this machine",
verified: true
})
Use memory_type: error (something broke), correction (the user fixed you), lesson (a better way found).
2. Detect recurrence → promote. Before saving, clawvault_search the pattern-key. If the lesson already exists, it recurred — promote it: save a sharpened version with higher importance and supersedes:[oldId]. Recurring pain earns higher importance.
3. Graduate proven lessons. When a lesson keeps mattering, raise its importance so it surfaces first in recall. If it's important enough to load every session, suggest to the user that they add it to their AGENTS.md — do not edit instruction files yourself. Auto-modifying always-loaded guidance is a prompt-injection risk (an attacker-supplied "lesson" could become permanent instructions); that decision belongs to the user.
4. Reflect after real work. When a task completes, log a short reflection:
5. Review before you start. Before a major or repeated task, clawvault_search prior lessons/errors on that topic so you don't repeat a known mistake.
The rules (verify-before-save)
Never present a guess as a fact. If unchecked, say "I'm not certain — let me verify."
Prefer ground truth (run/read/fetch) over your own memory.
Record the source on every saved fact. A memory with no source is a hypothesis.
Only verified facts become memories; unverified → memory_type: "unverified".
Tell-vs-do: if you claim you saved something, verify it actually landed. Never claim, always check.
The 3-question test
Before stating or saving any claim: (1) Where did I learn this? (2) Can I check it cheaply now?
(3) What would prove me wrong? If the honest answer to #1 is "it just feels right" — stop and verify.
Tools this skill uses
clawvault_save — store a memory (with source, verified, dedup guard, supersedes)
clawvault_search — FTS5 relevance-ranked recall
clawvault_recent — timeline of recent memories
clawvault_consolidate — cluster related memories to synthesize into one insight
Run these three. Each catches a failure that otherwise stays completely silent.
text
1. Did I get the right plugin?
Ask the agent to list its tools, or try: clawvault_stats
✅ want: it returns memory counts
🔴 "unknown tool" → you installed a different ClawVault. See below.
2. Is the database there?
ls -la ~/.openclaw/memory/clawvault.db
✅ want: a file
🔴 missing → the plugin never initialised
3. Does a round-trip work?
clawvault_save({ content: "install check", memory_type: "fact" })
clawvault_search({ query: "install check" })
✅ want: the note comes back
Did I install the wrong one?
Symptoms: a clawvaultcommand-line tool exists, a ~/.cache/qmd folder appeared,
~2 GB was downloaded, or the tools are named clawvault search rather than clawvault_search.
That is not this plugin. Removing it is a manual job for the human, not the agent.
🛑 Agents: do not perform these removals. Show this section to the user and let them
decide. Never delete a path on someone's behalf.
To the human reading this — four steps, in your own terminal:
Disable the wrong hook — openclaw hooks disable clawvault
Look at ~/.openclaw/hooks/clawvault, confirm it is the wrong plugin's hook, and
delete that folder yourself.
Look at ~/.cache/qmd — that is the ~2 GB model cache the other package downloads.
The correct plugin never uses this path. Delete it if you want the space back.
Uninstall the two command-line tools — npm uninstall -g clawvault qmd
Inspect each folder before removing it. Only you can see what is actually on your machine.
⚠️ Your own memories are safe. They live in ~/.openclaw/memory/clawvault.db, which is
not touched by any of the four steps above.
🔴 Use the full name openclaw-plugin-clawvault. The short form clawhub:clawvault
resolves to an unrelated third-party package by another author that merely shares the
name. Installing that one gives you a skill that loads, reports ✓ Ready, and cannot
work — the clawvault_* tools this skill calls do not exist in it — and it downloads
~2 GB of models this skill has no use for.
Same plugin, either source: the ClawHub package above and
github.com/davidtkeane/openclaw-plugin-clawvault
are the same code. ClawHub is easier — one command, dependency (typebox) and prebuilt
dist/ included, no clone or npm install. Use GitHub if you want to read or build the
source yourself.
(v1.1.4 and earlier pointed at clawhub:clawvault or said GitHub-only. Both were
wrong — the command above is correct.)
What the correct plugin actually is
Storage
local SQLite + FTS5 at ~/.openclaw/memory/clawvault.db
