Clawmem

Memory lifecycle (pin / snooze / forget — manual tools)

• memory_pin (lifecycle retention + priority among relevance-equivalent results; +0.3 boost on composite surfaces, exact-tie precedence on raw routes) — PROACTIVELY when: user says "remember this"/"important"; an architecture/critical decision was just made; a user preference/constraint should persist across sessions. Do NOT pin routine/session-specific items.
• memory_snooze — PROACTIVELY when a memory keeps surfacing but isn't relevant now, user says "not now"/"later", or content is time-boxed.
• memory_forget — only when genuinely wrong or permanently obsolete. Prefer snooze for temporary suppression.
• ClawMem never physically deletes a document row (v0.30.0). Every lifecycle operation above is reversible: pin/snooze are metadata, forget and archive deactivate, contradiction handling only erodes confidence. Retention archives — lifecycle_restore brings it back — and purge_after_days is inert. Through v0.29.0 it permanently deleted archived rows from a non-dry-run sweep and from the SessionStart hook, unreported.
• Contradiction auto-resolution (judge-gated, v0.29.0): runs ONLY when a judge is configured via CLAWMEM_JUDGE_* — disabled (audited no-op) otherwise. With a judge: when decision-extractor detects a new decision contradicting an old one, the old one's confidence is lowered automatically (−0.25, floor 0.2). It stays retrievable; only its ranking drops. Removing it from retrieval outright (invalidated_at) is a separate, opt-in step behind CLAWMEM_CONTRADICTION_INVALIDATE, and applies only to content_type='observation' — a superseded decision is eroded, never retired, so do NOT tell a user that contradiction handling will retire a prior decision. Unarmed it logs WOULD invalidate and writes nothing. Do NOT suggest arming it without the vault-specific calibration in docs/guides/contradiction-invalidation.md.

Operational gotchas (agent-facing)

• Empty context-surfacing → prompt < 20 chars (short memory-intent queries like "what did I say?" are exempt — they force retrieval), starts with /, or nothing scored above threshold. Check clawmem status (doc counts) + embedding coverage.
• Vector search empty but BM25 works → missing embeddings (the watcher indexes but does NOT embed). Run clawmem embed or wait for the embed timer.
• intent_search weak for WHY/ENTITY → sparse graph. Run build_graphs (temporal backbone + semantic edges). Otherwise don't run it after every reindex — A-MEM links per-doc automatically.
• Rankings look RRF-flat / reranker suspect → clawmem rerank-health. A mis-served reranker (e.g. a GGUF that drops the score head) returns HTTP 200 but inert, non-discriminating scores, silently collapsing ranking to RRF. The reranker is a separately served model, not a bundled one — verify it discriminates, don't assume liveness = correctness.
• Index-run summary shows a ✎ notes gap (or [amem] LLM returned null per doc) → the LLM endpoint is dead, squatted, or misconfigured — clawmem doctor shape-probes CLAWMEM_LLM_URL with a real completion (v0.37.0). Persistent HTTP errors trip the 60s cooldown so the fallback engages where permitted; under CLAWMEM_NO_LOCAL_MODELS=true enrichment stays empty until fixed.
• Intermittent UserPromptSubmit hook timed out after 8s — output discarded → fixed in v0.16.0 (upgrade). Root cause was not inference or host RAM alone: the vector leg ran a synchronous sqlite-vec scan the timeout race could not bound, and writable hook opens could wait out busy_timeout on an unconditional backfill UPDATE. v0.16.0 bounds both with real deadlines; v0.20.0 adds the hard cap (run clawmem watch — the vector daemon runs the blocking scan off the hook's event loop, so a cold scan falls back to FTS instead of blocking the turn); v0.38.0 derives every in-handler deadline from CLAWMEM_HOOK_BUDGET_MS (default 6000ms) and requires the host timeout ≥ 1.5s startup + budget (clawmem setup hooks writes both; clawmem doctor checks). A timed-out hook silently drops that turn's <vault-context> (degraded recall, no error). A cold OS page cache still adds first-call latency, so host RAM headroom helps the margin — but it is the margin, not the fix. Full detail: docs/troubleshooting.md → Hooks slow or near timeout / Tuning the context-surfacing hook timeout.
• A known document is absent from search/vsearch/query but get by path returns it → it is invalidated (documents.invalidated_at IS NULL is a hard predicate on the FTS and both vector joins, with no query-time signal). On documents the only writer is contradiction invalidation, and only when armed — the invalidated_at in consolidation.ts is a different table. Diagnose + restore: docs/troubleshooting.md.
• A file an editor or agent saved never re-indexes until clawmem update → an atomic save (temp file renamed over the target) on Bun < 1.4.0, which reports it under the temp name. Fixed in v0.40.2 (the watcher rescans a directory after any event); on older versions upgrade Bun to 1.4.0+ and restart the watcher. Detail: docs/troubleshooting.md.
• Files in a directory made after the watcher started never re-index until clawmem update → the watcher walked each collection path once, at start (a new Claude Code project's memory/ is the common case). Fixed in v0.40.3 (a rescan watches new directories, within CLAWMEM_WATCH_MAX_DIRS); on older versions restart the watcher after new directories appear. Detail: docs/troubleshooting.md.
• Access counts or co-activations look reset after an upgrade to v0.41.0 → expected: the watcher's first start recomputed them from verified references (a turn that names a surfaced note, once per turn), so they start near zero and grow with real use. Through v0.40.3 every Stop counted the whole session again. clawmem doctor shows the stop pipeline's state; an ✗ for an older writer means some ClawMem process sharing the vault was not upgraded. Detail: docs/guides/upgrading.md.
• Stop-hook ranges keep coming back as model unavailable while the LLM server is up → v0.41.0's observer prompt could pass the 4,096-token context the docs prescribe for the observer model, and the server refused it (HTTP 400). Fixed in v0.41.1 (the CONTEXT section and the transcript share the 8,000-character budget); upgrade the hooks and restart the watcher; each queued range is due again within 12 hours and replays when the watcher or a later Stop runs. Detail: docs/troubleshooting.md.
• Stop-hook ranges stay quarantined on dense turns (hashes, JSON, logs, non-Latin text), or clawmem doctor counts ranges held as capacity: → v0.41.1's bound was in characters, and dense text filled the context and cut the observer's reply. Fixed in v0.41.2: the observer fits each prompt in tokens to the server's own context, keeps room for its reply, and runs a long turn as checkpointed windows. Serve the observer model with -c 8192; capacity: ranges replay by themselves once the context is raised. Detail: docs/troubleshooting.md.
• Stop-hook ranges held as no parseable response, or a turn with real work committed with no observation → the observer model's replies did not follow the schema (a transcript role as the type, a copied placeholder, its query-expansion format, which v0.41.3 read as "nothing"). Fixed in v0.41.4: only <none/> means "nothing", the prompt names the allowed types, a format retry names the failing field, and the observer asks llama-server for a grammar that admits only well-formed replies. Retry held ranges now with clawmem repair stop-queue --retry-now held --run; clawmem doctor groups what stays held by class. Detail: docs/troubleshooting.md.
• Anything setup-shaped (download blocked, server unreachable, watcher memory bloat or its per-collection directory cap, indexer bugs) → docs/troubleshooting.md. This skill does not duplicate it.

Anti-patterns

• ❌ Manually pick query/intent_search/search when memory_retrieve can auto-route → ✅ memory_retrieve first.
• ❌ Call MCP tools every turn → ✅ only when the 3-rule gate fires.
• ❌ Re-search what's already in <vault-context>.
• ❌ Run status routinely → ✅ only when retrieval feels broken or after large ingestion.
• ❌ Pin everything → ✅ pin only persistent high-priority items.
• ❌ Forget memories to "clean up" → ✅ let decay + contradiction detection handle it.
• ❌ build_graphs after every reindex → ✅ only after bulk ingestion or when graph traversal is weak.
• ❌ diary_write in Claude Code → ✅ hooks capture this automatically (diary is for non-hooked envs only).
• ❌ kg_query for causal "why" → ✅ intent_search (kg_query is entity facts, not reasoning chains).

Curator agent

Maintenance agent for Tier-3 work the main agent neglects. Invoke: "curate memory" / "run curator" / "memory maintenance". Six phases: (1) health snapshot, (2) lifecycle triage (pin/snooze/propose-forget — never auto-confirms), (3) retrieval health probes, (4) reflect + consolidate --dry-run, (5) conditional graph rebuild, (6) collection hygiene. Safety rails: never auto-confirms forget, never runs embed, never edits config.

Tool selection (one-liner)

memory_retrieve(query) | query(compact=true) | intent_search(why/when/entity) | query_plan(multi-topic) -> multi_get -> search/vsearch (spot checks)

Setup / config / internals → AGENTS.md + docs/

This skill is operations-only. For installation, inference-server setup (the embedding/LLM/reranker services — the SOTA reranker needs the zerank-2 GGUF that carries its score head, or the seq-cls sidecar), environment variables, systemd units, indexing/collection config, graph internals, and the OpenClaw (kind: memory) / Hermes (MemoryProvider) plugins, see AGENTS.md and docs/:

• Inference stack choice + server setup → docs/guides/inference-services.md
• All environment variables → docs/reference/configuration.md
• Cloud embedding → docs/guides/cloud-embedding.md
• Setup (hooks / mcp / systemd) → docs/guides/setup-hooks.md, docs/guides/setup-mcp.md, docs/guides/systemd-services.md
• Internals (pipelines, graph, entities) → docs/internals/
• OpenClaw / Hermes plugins → docs/guides/openclaw-plugin.md, docs/guides/hermes-plugin.md
• Troubleshooting → docs/troubleshooting.md