Memory (vault)

Plugin ID: clawql-memory
Package: packages/clawql-memory — MemoryPlugin

Persists durable session knowledge to an Obsidian-compatible vault and recalls it across chats. Agents should start with memory_recall (optionally with sources) and open read_around only when they need the enclosing Markdown section.

8.0: ClawQL PageIndex (pageindex_*, hybrid PageIndex, pageindex.db.json) and CodeGraph (codegraph_*, Graphify import/sync, clawql-codegraph) are both removed. See purge inventory, post-8.0 Vectify backlog, and post-8.0 CodeGraph backlog.

Memory 2.0 components

Each piece has one job. The vault is the only canonical store; everything else is a derived index, a code index, an external peer, or the recall facade.

Component	Used for	Unique role
Obsidian / Vault	Store knowledge as Markdown + YAML frontmatter under `Memory/`	Canonical core every derived index and query path references or cites back into
Wikilinks + `memory.db`	Parse `[[links]]` into SQLite (`wikilink_edge`, `vault_chunk`) on ingest; traverse on recall	Explicit structured graph over the vault — link navigation without vectors
Embeddings	Vector representations of vault chunks for similarity in `memory_recall`	Fuzzy semantic retrieval when no wikilinks or structural paths exist
Onyx	`knowledge_search_onyx` / `sources: ["onyx"]`; optional `enterpriseCitations` on ingest	External search peer — supplies org knowledge without ClawQL owning the corpus

Write once, refresh indexes: memory_ingest always writes vault Markdown. Optional rebuild refreshes derived layers (memory.db/embeddings). Onyx stays a search peer (citations into the vault, not “ingest into Onyx”).

Agent habit: start with memory_recall (sources when needed) → follow followUps into specialists only when you need path / filtered enterprise search.

Erasure

Git-native vaults (CLAWQL_MEMORY_BACKEND=git) encrypt Memory notes with per-note keys (crypto-shredding). Erase destroys the key so history/R2 ciphertext is unreadable; WORM records opaque pathId + content hash only; erased hashes feed the inference export deny-list.

Env	Default	Role
`CLAWQL_MEMORY_BACKEND=git`	off	Commit-on-ingest; enables crypto-shred by default
`CLAWQL_MEMORY_CRYPTO_SHRED`	on when backend=`git`	Force `1`/`0` to enable/disable per-note encryption
`.clawql/note-keys/`	gitignored	Per-note AES keys — destroyed on erase
`.clawql/path-map.json`	gitignored	Readable path ↔ opaque `pathId` (erasable)
`.clawql/erasure-deny.json`	gitignored	Content hashes skipped by `clawql inference export`

Full write-up: memory-obsidian § Erasure · gateway ladder § Erasure · site: Learn memory.

MCP tools

Tool	Purpose
`memory_ingest`	Write structured insights, wikilinks, and optional verbatim tool output to the vault
`memory_recall`	Multi-source recall (`sources`) → `hits[]` + `followUps`; vault `results` kept
`read_around`	Expand a path/chunk hit into the enclosing Markdown heading section

`memory_recall` sources

{
  "query": "AuthService rate limit",
  "sources": ["vault", "vector", "onyx"],
  "limit": 10,
  "maxDepth": 2
}

Source	What it contributes
`vault`	Lexical + wikilink BFS over Obsidian Markdown (ranker: IDF)
`vector`	Embedding KNN seeds (when vector backend + API key configured)
`onyx`	Enterprise citations via injected Onyx search

Defaults when sources is omitted: vault + vector, plus the Onyx hybrid from env (CLAWQL_MEMORY_RECALL_HYBRID_ONYX).

Response:

results — vault-side hits (backward compatible)
hits — normalized multi-source hits (source, id, score, snippet, …)
followUps — specialist tool hints (knowledge_search_onyx, …)
sourcesUsed / sourceNotes — what ran and skip reasons
vaultRanker — always idf when vault was queried (bm25 removed in 8.0.0 — purge, wash vs IDF)

Vault lexical ranker

Env	Default	Effect
`CLAWQL_MEMORY_VAULT_RANKER=idf`	idf	Corpus IDF × log-TF (#801); only mode — `bm25` removed in 8.0.0 (wash vs IDF, see purge inventory)

`memory_ingest` rebuild

{
  "title": "AuthService rate limits",
  "insights": "## Finding\n…",
  "wikilinks": ["API hardening"],
  "enterpriseCitations": [],
  "rebuild": { "embeddings": true }
}

Flag	Effect
`rebuild.embeddings`	Run memory.db / embedding sync (default on when memory.db enabled; `false` skips)

Enable / disable

Env	Default	Effect
`CLAWQL_ENABLE_MEMORY=0`	on	Omit `MemoryPlugin` and hide memory tools
`CLAWQL_MEMORY_RECALL_HYBRID_ONYX=1`	off	Default `sources` includes onyx (needs Onyx wired + enabled)
`CLAWQL_MEMORY_VAULT_RANKER`	`idf`	Vault lexical ranker — `idf` is the only mode (`bm25` removed in 8.0.0)

Prerequisites

Writable CLAWQL_OBSIDIAN_VAULT_PATH (Docker images often use /vault)
Tools register even without a vault path, but vault I/O fails until the path is configured
Onyx in sources: CLAWQL_ENABLE_ONYX=1 + documents/onyx in merge; MCP wires search into memory

Optional hybrid vector index: see memory-db-hybrid-implementation.md in the repo.

Typical workflow

memory_recall with a focused query (add sources when you need code/enterprise in one shot)
Follow followUps only when you need path or filtered Onyx
Do work with search / execute
memory_ingest with decisions + wikilinks

Learn more

Lifelong guided traversal (P2 plan) — MAPF-inspired warm-start / receding-horizon / local-guidance recall
Post-8.0 CodeGraph revisit — why codegraph_* was purged and conditions for revival
clawql-memory (Memory 2.0)
MCP tools § memory