Durable context with memory_ingest and memory_recall

memory_ingest and memory_recall are the pair you use when context should survive MCP server restarts, pod reschedules, or starting a new chat days later. They read and write Markdown under an Obsidian-style vault path (plus an optional memory.db sidecar for hybrid recall)—not the in-process cache map.

For same-process scratch state only, see Cache handoff between chats and Session cache.

Why this persists (and how it differs from cache)

After memory_ingest writes, ClawQL can refresh search indexes and memory.db so memory_recall can score notes by keywords, wikilink graph hops, and (when configured) vectors—see memory-obsidian.md.

Storage you must provide (local dir or PVC)

Vault memory is only real if the server has a writable place for files.

1. Set CLAWQL_OBSIDIAN_VAULT_PATH to a directory that already exists and is writable by the ClawQL process at startup (see mcp-tools.md § memory_ingest).
2. memory_ingest creates pages under Memory/<slug>.md with YAML frontmatter; memory_recall scans that tree (subject to CLAWQL_MEMORY_RECALL_* defaults).

Local / VM / bare Docker

• Choose a folder on disk (for example ~/ClawQL-vault), ensure permissions match the user running clawql-mcp, export CLAWQL_OBSIDIAN_VAULT_PATH to that path.
• Back up the directory like any other data you care about.

Kubernetes

• The container filesystem alone is ephemeral: if you do not mount storage, notes disappear when the pod is recreated.
• Use a PersistentVolumeClaim (or another supported volume type) mounted at the path you pass as CLAWQL_OBSIDIAN_VAULT_PATH (images often default to something like /vault—override to match your mount).
• For more than one replica, use a volume that is shared read-write across pods (RWX) so every pod sees the same Markdown; otherwise each replica has its own isolated vault.
• Local Docker Desktop flows in this repo often use hostPath for a vault under $HOME/.ClawQL—see Kubernetes (CLAWQL_LOCAL_VAULT_HOST_PATH) and Helm.

Managed platforms (for example Cloud Run) treat unattached disk as ephemeral unless you add a mounted volume; see deploy-cloud-run.md for the same constraint in prose.

Before you start

1. Confirm CLAWQL_ENABLE_MEMORY is not set to 0 (tools hidden).
2. Confirm CLAWQL_OBSIDIAN_VAULT_PATH points at your real vault and that Memory/ can be created or updated.
3. ingest and recall must use the same vault root—path mismatches between environments produce empty recall or writes you cannot see (see case study).
4. Treat vault Markdown as sensitive if you put secrets inside; prefer redaction and short-lived tokens in prose.

Pattern: checkpoint with memory_ingest

At the end of a thread (or after a milestone), persist a distilled note: goal, done, next, constraints, links. Use a title you can memory_recall against later.

memory_ingest (minimal)

{
  "title": "Handoff — Acme API hardening",
  "insights": "## Goal\nLock down the Acme public API review workflow.\n\n## Done\n- OpenAPI merge uses CLAWQL_SPEC_PATH + bundled slack\n\n## Next\n1. execute slack::conversations_list\n2. Post summary to #review-bot\n\n## Constraints\n- Branch feat/api-review; no production executes",
  "append": true,
  "wikilinks": ["Slack MCP", "Security review"]
}

Optional fields include conversation, toolOutputs, toolOutputsFile (server-side file allowlist), enterpriseCitations, sessionId—full table in mcp-tools.md § memory_ingest.

Re-using the title with append: true (default) appends a new dated section instead of overwriting the whole note—good for running threads.

Pattern: hydrate with memory_recall

In a new chat (or after a restart), pull vault context before planning.

memory_recall

{
  "query": "Acme API hardening slack review",
  "limit": 8,
  "maxDepth": 2
}

Responses include results[] with path, snippet, score, reason (keyword, link, or vector when embeddings are configured). Turn the snippets into your working set—or ask the agent to quote them and continue.

Tune limit, maxDepth, and minScore to balance noise vs coverage (see mcp-tools.md § memory_recall).

Stable titles, wikilinks, and append

• Stable title — same string across sessions builds one note file agents can grow over time (append threading).
• wikilinks — pass related note titles (for example ["Slack MCP", "Security review"]) so ingest can link pages for graph recall; see memory-obsidian.md.
• Obsidian (optional) — open the same folder in Obsidian to inspect what agents wrote.

Limits and pitfalls

• No vault path — tools may be registered but writes/recall require a valid CLAWQL_OBSIDIAN_VAULT_PATH.
• Read-only mount — memory_ingest fails; fix volume permissions or mount options.
• Replicas without shared storage — each pod’s vault diverges; use one replica or RWX PVC.
• Large logs — use toolOutputsFile with CLAWQL_MEMORY_INGEST_FILE_ROOTS instead of megabyte toolOutputs in JSON.
• Canonical reference: memory-obsidian.md, mcp-tools.md, integrations/cursor-vault-memory.md.

When cache is still enough

Use cache when everything happens on one long-lived process and you only need a throwaway handoff key. Move to memory_ingest / memory_recall when restarts, shared teams, or audit-friendly Markdown matter.

See also: Cache handoff between chats · Session cache · Tools · ClawQL Learn overview