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. The same plugin tier also registers PageIndex and optional code graph specialists. Agents should start with memory_recall (optionally with sources) and open specialist tools only when they need path/tree/enterprise depth.

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
PageIndex	`pageindex_build_tree` → heading tree in `pageindex.db.json`; traverse / synthesize	Deterministic, vectorless section navigation and token-budget synthesis on vault structure
clawql-codegraph	Parse source (TS compiler API for TS/JS; tree-sitter WASM for Python/Go) → nodes/edges with confidence tags	Deterministic structural index over code, independent of the vault
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 (PageIndex, memory.db/embeddings). Codegraph indexes code; 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 / tree walk / filtered enterprise search.

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
`pageindex_build_tree`	Build a vectorless hierarchical index from Markdown (`clawql-pageindex`)
`pageindex_traverse`	Walk the PageIndex tree under a token budget
`pageindex_synthesize`	Merge selected nodes into agent context
`pageindex_get_content`	Read indexed node content
`codegraph_index`	Build structural code graph from repo root (`clawql-codegraph`, opt-in)
`codegraph_import_graphify`	Import Graphify `graph.json` (NetworkX node-link export)
`codegraph_query`	Find symbols by name or concept in the code graph
`codegraph_neighbors`	List inbound/outbound edges (imports, calls, contains)
`codegraph_path`	Shortest path between two symbols (Graphify-style trace)
`codegraph_explain`	Summarize a symbol and its neighborhood
`codegraph_subgraph`	BFS subgraph around a seed query

`memory_recall` sources

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

Source	What it contributes
`vault`	Keyword + wikilink BFS over Obsidian Markdown
`vector`	Embedding KNN seeds (when vector backend + API key configured)
`codegraph`	Structural symbol hits (`codeGraphHits` + normalized hits)
`pageindex`	Term-overlap heading nodes from stored PageIndex trees
`onyx`	Enterprise citations via injected Onyx search

Defaults when sources is omitted: vault + vector, plus hybrids from env (CLAWQL_MEMORY_RECALL_HYBRID_CODEGRAPH, _PAGEINDEX, _ONYX) or includeCodeGraph: true.

Response:

results — vault-side hits (backward compatible)
hits — normalized multi-source hits (source, id, score, snippet, …)
followUps — specialist tool hints (pageindex_synthesize, codegraph_path, knowledge_search_onyx, …)
sourcesUsed / sourceNotes — what ran and skip reasons

`memory_ingest` rebuild

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

Flag	Effect
`rebuild.pageindex`	Rebuild PageIndex for the written note (or set `CLAWQL_MEMORY_INGEST_REBUILD_PAGEINDEX=1`)
`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 + PageIndex + code graph tools
`CLAWQL_ENABLE_PAGEINDEX=0`	on	Hide `pageindex_*` only (memory ingest/recall remain)
`CLAWQL_ENABLE_CODEGRAPH=1`	off	Register `codegraph_*` tools (structural code graph)
`CLAWQL_MEMORY_RECALL_HYBRID_CODEGRAPH=1`	off	Default `sources` includes codegraph
`CLAWQL_MEMORY_RECALL_HYBRID_PAGEINDEX=1`	off	Default `sources` includes pageindex
`CLAWQL_MEMORY_RECALL_HYBRID_ONYX=1`	off	Default `sources` includes onyx (needs Onyx wired + enabled)
`CLAWQL_MEMORY_INGEST_REBUILD_PAGEINDEX=1`	off	Rebuild PageIndex after every successful ingest

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
Code graph: CLAWQL_CODEGRAPH_ROOT + CLAWQL_CODEGRAPH_PATH
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/PageIndex in one shot)
Follow followUps only when you need path, tree synthesize, or filtered Onyx
Do work with search / execute
memory_ingest with decisions + wikilinks; set rebuild.pageindex: true for long notes

PageIndex workflow

Standalone MIT library for vectorless hierarchical document indexing (Markdown headings → tree → traverse → synthesize), registered as MCP tools by MemoryPlugin:

Ingest long docs with memory_ingest or ingest_external_knowledge
pageindex_build_tree on vault Markdown (pass a docId)
pageindex_traverse / pageindex_synthesize instead of pasting full files into the thread

Package API: packages/clawql-pageindex/README.md

Learn more

Lifelong guided traversal (P2 plan) — MAPF-inspired warm-start / receding-horizon / local-guidance recall
Code graph plugin — Graphify import, tree-sitter languages, env reference
clawql-memory (Memory 2.0)
MCP tools § memory