Why ClawVault?

Most agent memory relies on an embedding index — which can silently drift, corrupt, or fall out of sync (and then "memory search is disabled" right when you need it). ClawVault takes the boring, bulletproof path: SQLite's battle-tested FTS5 full-text engine.

• 🔍 Fast, ranked recall — BM25 relevance scoring, not a linear scan.
• 🧱 Nothing to rebuild — no vectors, no re-embedding, no index that can mismatch.
• 📦 One portable file — open it with any SQLite tool, inspect it, ship it.
• ⚙️ Zero native build — uses Node's built-in node:sqlite. No node-gyp, no headaches.
• 🛡️ Verify-before-save — every memory can record where it came from and whether it was checked.

✨ The distinctive bit: verify-before-save

Any model — small or large — can produce confident text that's simply wrong. A memory that stores a made-up "fact" is worse than no memory, because it launders a guess into "something we know." ClawVault makes honesty part of the schema:

• clawvault_save takes a source (URL, command, file, person) and a verified boolean.
• Verified facts are facts. Unverified ones get memory_type: "unverified" — a question to confirm, not a truth to trust.
• The rule the agent follows: search before you answer, verify before you save, always record the source.

🔍 The doctrine in action

Ask the agent a factual question and — instead of answering from memory — it searches first, then grounds its reply in cited sources (and treats the web result as untrusted content). The same setup used to answer instantly from memory; with the verify-before-answer discipline it checks first:

🛠️ Tools

Keeping memory clean (v0.3)

• Duplicate guard — clawvault_save compares new content against existing memories (FTS + term overlap). A near-identical memory (≥ dedupThreshold, default 0.85) is refused with the id of the existing one, so the store doesn't fill with restated facts. Pass force:true to override.
• Consolidation — clawvault_consolidate returns a cluster of related memories so the agent can distil them into one higher-level insight, then clawvault_save(..., supersedes:[ids]) soft-retires the raw rows. Superseded memories are hidden from search/recent by default (include_superseded:true to see them) — nothing is ever deleted.
• Verified-claim guard (v0.4) — clawvault_save auto-downgrades verified:true to unverified unless source shows evidence of a real check (a command, URL, file path, or a user statement). A confident recollection can't masquerade as a checked fact — the store defends its own integrity instead of trusting the model. Disable with strictVerification:false.
• Linked memories / knowledge graph (v0.5) — clawvault_relate(from_id, rel, to_id) connects two memories with a typed edge (caused_by, depends_on, relates_to, contradicts…), and clawvault_links(id) shows a memory's neighbourhood. Consolidation auto-records supersedes edges, so the graph builds itself as you curate. Flat recall (FTS5) plus structured connections.

📥 Install

From ClawHub (recommended):

openclaw plugins install clawhub:openclaw-plugin-clawvault
openclaw gateway restart

⚠️ Use the full name openclaw-plugin-clawvault. The short clawhub:clawvault resolves to an unrelated third-party package — not this plugin. This one command fetches the published package, installs its dependency (typebox), and uses the prebuilt dist/ — no clone or npm install needed.

From source (for development / running the tests):

git clone https://github.com/davidtkeane/openclaw-plugin-clawvault
cd openclaw-plugin-clawvault
npm install
npm run plugin:build
openclaw plugins install ./
openclaw gateway restart

Trust the locally-installed plugin (silences the "untracked local code" notice) by adding to ~/.openclaw/openclaw.json:

{ "plugins": { "allow": ["clawvault"], "entries": { "clawvault": { "enabled": true } } } }

🧭 Recommended agent setup

Installing the plugin gives your agent the tools. To get the behavior — an agent that searches its memory before answering and only saves what it has verified — add this to your agent's instructions (e.g. ~/.openclaw/workspace/AGENTS.md). The full rationale is in DOCTRINE.md.

## 🔍 Verify Before You Save (ClawVault)

- Before answering a factual question, run `clawvault_search` first — don't guess what you already stored.
- Prefer ground truth over memory: run the command / read the file / query the DB / check the internet.
- After learning a VERIFIED fact, `clawvault_save` it with a `source` and `verified: true`.
- Never save something you haven't checked. If unverified, set `memory_type: "unverified"`.
- Tell-vs-do: if you claim you saved or changed something, verify it actually happened. Never claim, always check.
- The 3-question test before stating/saving anything: (1) Where did I learn this? (2) Can I check it cheaply now? (3) What would prove me wrong?

That one block turns ClawVault from "a memory that can record sources" into "a memory that only trusts what was checked."

⚙️ Configuration

🧠 The seed layer

A brand-new database is seeded with a small set of generic operating rules (verify-before-save, tell-vs-do, confirm-before-destructive) so the agent starts with good memory discipline. No personal identity or persona is injected. Turn it off entirely with seedIdentity: false.

🔒 Privacy & data

ClawVault stores conversation-derived memories (facts, decisions, preferences, corrections that you or the agent choose to save) in a local SQLite file — by default ~/.openclaw/memory/clawvault.db.

• ClawVault itself makes no network calls — stored data never leaves your machine (no telemetry, no external transmission). Separately, when you ask the agent to verify a fact, it may use its own web-search/fetch tools — that's the agent, not ClawVault.
• Data persists across sessions and is recalled later — that's the point. Saved content is retained until you remove it, so be mindful of what you ask it to remember.
• You stay in control: set dbPath wherever you like, use seedIdentity: false to skip the seed, and edit or delete the SQLite file directly at any time (it's a plain database). Superseded memories are hidden, not deleted — remove rows manually if you need them gone.

🗄️ Schema

CREATE TABLE memories (
  id            INTEGER PRIMARY KEY AUTOINCREMENT,
  timestamp     TEXT NOT NULL,
  memory_type   TEXT,
  content       TEXT NOT NULL,
  importance    INTEGER DEFAULT 6,
  keywords      TEXT,
  source_machine TEXT,
  ranger_id     TEXT,
  source        TEXT,          -- where this fact came from
  verified      INTEGER DEFAULT 0  -- 1 only if actually checked
);

CREATE VIRTUAL TABLE memories_fts USING fts5(content, keywords, content='memories');

Triggers keep memories_fts in sync automatically on insert / update / delete. Older databases are migrated in place (the source and verified columns are added on first use).

Backing up: the DB runs in WAL mode, so the latest writes live in a -wal sidecar — a plain cp of the .db alone can miss them. Use a consistent copy: sqlite3 ~/.openclaw/memory/clawvault.db ".backup /path/to/backup.db".

🧑‍💻 Development

Requires Node 22.22.3+ / 24.15+ / 25.9+ and openclaw >= 2026.5.17.

npm install
npm run plugin:build      # tsc + `openclaw plugins build` (regenerates the manifest)
npm run plugin:validate   # tsc + `openclaw plugins validate`
npm test                  # vitest

The plugin is a single defineToolPlugin in src/index.ts — the whole thing is one readable file.

🧪 Testing

Two layers — see TESTING.md for the full guide.

Layer A — plugin mechanics (deterministic, no model, no network). Drives every tool against a throwaway SQLite DB and asserts dedup, the verified-claim guard, consolidation, and the relation graph. This is the regression net — run it anywhere:

npm test        # vitest: src/*.test.ts

Layer B — model hallucination / honesty eval (needs an OpenAI-compatible endpoint such as exo with a model loaded). Sends trap questions (nonexistent commands, flags, places, endpoints; a from-memory hash) and scores whether the model declines (good) or fabricates (bad) — running each bare vs doctrine-primed so you can measure the doctrine's effect and compare models:

node scripts/eval.mjs --model <model-id> --endpoint http://127.0.0.1:52415 --out report.json

Verdicts are heuristic (PASS / FAIL / REVIEW); the report keeps every response for review. Example run (Qwen3-Coder-Next-4bit): honesty 80% bare → 100% doctrine-primed — the verify-before-answer prompt measurably reduced fabrication.

🙏 Credits & inspiration

ClawVault borrows ideas from these open-source OpenClaw projects — credited here in the spirit of ClawVault's own rule: always record the source. All are permissively licensed (MIT / MIT-0), so attribution isn't required — we give it anyway. Ideas were reimplemented for ClawVault's SQLite+FTS5 model; no code was copied.

📄 License

MIT © 2026 David Keane. See LICENSE.