clawmem 0.4.2 → 0.5.1

package/AGENTS.md

@@ -307,9 +307,15 @@ All other retrieval is handled by Tier 2 hooks. Do NOT call MCP tools speculativ
 4. Chain tracing → find_causal_links(docid, direction="both", depth=5)
    Traverses causal edges between _clawmem/agent/observations/ docs (from decision-extractor).
 
-5. Memory debugging → memory_evolution_status(docid)
+5. Entity facts → kg_query(entity, as_of?, direction?)
+   Structured SPO triples with temporal validity. Different from intent_search:
+   - kg_query: "what does ClawMem relate to?" → returns structured facts (subject-predicate-object)
+   - intent_search: "why did we choose ClawMem?" → returns documents with causal reasoning
+   Use kg_query for entity lookup, intent_search for causal chains.
 
-6. Temporal context → timeline(docid, before=5, after=5, same_collection=false)
+6. Memory debugging → memory_evolution_status(docid)
+
+7. Temporal context → timeline(docid, before=5, after=5, same_collection=false)
    Shows what was created/modified before and after a document.
    Use after search to understand chronological neighborhood.
 ```
@@ -327,6 +333,9 @@ All other retrieval is handled by Tier 2 hooks. Do NOT call MCP tools speculativ
 - `timeline(docid, before=5, after=5, same_collection=false)` — temporal neighborhood around a document. Progressive disclosure: search → timeline → get. Supports same-collection scoping and session correlation.
 - `list_vaults()` — show configured vault names and paths. Empty in single-vault mode (default).
 - `vault_sync(vault, content_root, pattern?, collection_name?)` — index markdown from a directory into a named vault. Restricted-path validation rejects sensitive directories (`/etc/`, `/root/`, `.ssh`, `.env`, `credentials`, etc.).
+- `kg_query(entity, as_of?, direction?)` — query the SPO knowledge graph for an entity's relationships. Returns temporal triples with validity windows. USE THIS for "what does X relate to?", "what was true about X in January?". Uses entity resolution for lookup.
+- `diary_write(entry, topic?, agent?)` — write a diary entry. USE PROACTIVELY in non-hooked environments (Hermes, Gemini, plain MCP) for recording important events and decisions. Do NOT use in Claude Code (hooks handle this automatically).
+- `diary_read(last_n?, agent?)` — read recent diary entries.
 
 ### Multi-Vault
 
@@ -354,6 +363,9 @@ Pin, snooze, and forget are **manual MCP tools** — not automated. The agent sh
 - Do NOT pin everything — pin is for persistent high-priority items, not temporary boosting.
 - Do NOT forget memories to "clean up" — let confidence decay and contradiction detection handle it naturally.
 - Do NOT run `build_graphs` after every reindex — A-MEM creates per-doc links automatically. Only after bulk ingestion or when `intent_search` returns weak graph results.
+- Do NOT run `clawmem mine` autonomously — it is a bulk ingestion command (same category as `update`/`reindex`). Suggest it to the user when they mention old conversation exports, but let them run it. Bulk import has disk/embedding cost implications that need user consent.
+- Do NOT use `diary_write` in Claude Code — hooks (`decision-extractor`, `handoff-generator`) capture this automatically. Diary is for non-hooked environments only (Hermes, Gemini, plain MCP clients).
+- Do NOT use `kg_query` for causal "why" questions — use `intent_search` or `memory_retrieve`. `kg_query` returns structured entity facts (SPO triples), not reasoning chains.
 
 ## Tool Selection (one-liner)
 
@@ -435,16 +447,16 @@ compositeScore = (0.10 × searchScore + 0.70 × recencyScore + 0.20 × confidenc
 
 | Content Type | Half-Life | Effect |
 |--------------|-----------|--------|
-| decision, hub | ∞ | Never decay |
+| decision, preference, hub | ∞ | Never decay |
 | antipattern | ∞ | Never decay — accumulated negative patterns persist |
 | project | 120 days | Slow decay |
 | research | 90 days | Moderate decay |
-| note | 60 days | Default |
-| progress | 45 days | Faster decay |
+| problem, milestone, note | 60 days | Default |
+| conversation, progress | 45 days | Faster decay |
 | handoff | 30 days | Fast — recent matters most |
 
 Half-lives extend up to 3× for frequently-accessed memories (access reinforcement decays over 90 days).
-Attention decay: non-durable types (handoff, progress, note, project) lose 5% confidence per week without access. Decision/hub/research/antipattern are exempt.
+Attention decay: non-durable types (handoff, progress, conversation, note, project) lose 5% confidence per week without access. Decision/preference/hub/research/antipattern are exempt.
 
 ## Indexing & Graph Building
 
@@ -563,6 +575,12 @@ Symptom: "Local model download blocked" error
   → llama-server endpoint unreachable while CLAWMEM_NO_LOCAL_MODELS=true.
   → Fix: Start the llama-server instance. Or set CLAWMEM_NO_LOCAL_MODELS=false for in-process fallback.
 
+Symptom: "[generate] Remote LLM in cooldown, falling back to in-process generation"
+  → Remote LLM server had a transport failure (ECONNREFUSED/ETIMEDOUT). ClawMem set a 60s cooldown
+    and is using local node-llama-cpp. Remote will be retried after cooldown expires.
+  → Not an error if you expect local fallback. If you want remote only: ensure llama-server is running,
+    or set CLAWMEM_NO_LOCAL_MODELS=true to get null instead of slow local inference.
+
 Symptom: Query expansion always fails / returns garbage
   → On CPU-only systems, in-process inference is significantly slower and less reliable. Systems with GPU acceleration (Metal/Vulkan) handle these models well in-process.
   → Fix: Run llama-server on a GPU. Even a low-end NVIDIA card handles 1.7B models.

package/CLAUDE.md

@@ -307,9 +307,15 @@ All other retrieval is handled by Tier 2 hooks. Do NOT call MCP tools speculativ
 4. Chain tracing → find_causal_links(docid, direction="both", depth=5)
    Traverses causal edges between _clawmem/agent/observations/ docs (from decision-extractor).
 
-5. Memory debugging → memory_evolution_status(docid)
+5. Entity facts → kg_query(entity, as_of?, direction?)
+   Structured SPO triples with temporal validity. Different from intent_search:
+   - kg_query: "what does ClawMem relate to?" → returns structured facts (subject-predicate-object)
+   - intent_search: "why did we choose ClawMem?" → returns documents with causal reasoning
+   Use kg_query for entity lookup, intent_search for causal chains.
 
-6. Temporal context → timeline(docid, before=5, after=5, same_collection=false)
+6. Memory debugging → memory_evolution_status(docid)
+
+7. Temporal context → timeline(docid, before=5, after=5, same_collection=false)
    Shows what was created/modified before and after a document.
    Use after search to understand chronological neighborhood.
 ```
@@ -327,6 +333,9 @@ All other retrieval is handled by Tier 2 hooks. Do NOT call MCP tools speculativ
 - `timeline(docid, before=5, after=5, same_collection=false)` — temporal neighborhood around a document. Progressive disclosure: search → timeline → get. Supports same-collection scoping and session correlation.
 - `list_vaults()` — show configured vault names and paths. Empty in single-vault mode (default).
 - `vault_sync(vault, content_root, pattern?, collection_name?)` — index markdown from a directory into a named vault. Restricted-path validation rejects sensitive directories (`/etc/`, `/root/`, `.ssh`, `.env`, `credentials`, etc.).
+- `kg_query(entity, as_of?, direction?)` — query the SPO knowledge graph for an entity's relationships. Returns temporal triples with validity windows. USE THIS for "what does X relate to?", "what was true about X in January?". Uses entity resolution for lookup.
+- `diary_write(entry, topic?, agent?)` — write a diary entry. USE PROACTIVELY in non-hooked environments (Hermes, Gemini, plain MCP) for recording important events and decisions. Do NOT use in Claude Code (hooks handle this automatically).
+- `diary_read(last_n?, agent?)` — read recent diary entries.
 
 ### Multi-Vault
 
@@ -354,6 +363,9 @@ Pin, snooze, and forget are **manual MCP tools** — not automated. The agent sh
 - Do NOT pin everything — pin is for persistent high-priority items, not temporary boosting.
 - Do NOT forget memories to "clean up" — let confidence decay and contradiction detection handle it naturally.
 - Do NOT run `build_graphs` after every reindex — A-MEM creates per-doc links automatically. Only after bulk ingestion or when `intent_search` returns weak graph results.
+- Do NOT run `clawmem mine` autonomously — it is a bulk ingestion command (same category as `update`/`reindex`). Suggest it to the user when they mention old conversation exports, but let them run it. Bulk import has disk/embedding cost implications that need user consent.
+- Do NOT use `diary_write` in Claude Code — hooks (`decision-extractor`, `handoff-generator`) capture this automatically. Diary is for non-hooked environments only (Hermes, Gemini, plain MCP clients).
+- Do NOT use `kg_query` for causal "why" questions — use `intent_search` or `memory_retrieve`. `kg_query` returns structured entity facts (SPO triples), not reasoning chains.
 
 ## Tool Selection (one-liner)
 
@@ -435,16 +447,16 @@ compositeScore = (0.10 × searchScore + 0.70 × recencyScore + 0.20 × confidenc
 
 | Content Type | Half-Life | Effect |
 |--------------|-----------|--------|
-| decision, hub | ∞ | Never decay |
+| decision, preference, hub | ∞ | Never decay |
 | antipattern | ∞ | Never decay — accumulated negative patterns persist |
 | project | 120 days | Slow decay |
 | research | 90 days | Moderate decay |
-| note | 60 days | Default |
-| progress | 45 days | Faster decay |
+| problem, milestone, note | 60 days | Default |
+| conversation, progress | 45 days | Faster decay |
 | handoff | 30 days | Fast — recent matters most |
 
 Half-lives extend up to 3× for frequently-accessed memories (access reinforcement decays over 90 days).
-Attention decay: non-durable types (handoff, progress, note, project) lose 5% confidence per week without access. Decision/hub/research/antipattern are exempt.
+Attention decay: non-durable types (handoff, progress, conversation, note, project) lose 5% confidence per week without access. Decision/preference/hub/research/antipattern are exempt.
 
 ## Indexing & Graph Building
 
@@ -563,6 +575,12 @@ Symptom: "Local model download blocked" error
   → llama-server endpoint unreachable while CLAWMEM_NO_LOCAL_MODELS=true.
   → Fix: Start the llama-server instance. Or set CLAWMEM_NO_LOCAL_MODELS=false for in-process fallback.
 
+Symptom: "[generate] Remote LLM in cooldown, falling back to in-process generation"
+  → Remote LLM server had a transport failure (ECONNREFUSED/ETIMEDOUT). ClawMem set a 60s cooldown
+    and is using local node-llama-cpp. Remote will be retried after cooldown expires.
+  → Not an error if you expect local fallback. If you want remote only: ensure llama-server is running,
+    or set CLAWMEM_NO_LOCAL_MODELS=true to get null instead of slow local inference.
+
 Symptom: Query expansion always fails / returns garbage
   → On CPU-only systems, in-process inference is significantly slower and less reliable. Systems with GPU acceleration (Metal/Vulkan) handle these models well in-process.
   → Fix: Run llama-server on a GPU. Even a low-end NVIDIA card handles 1.7B models.

package/README.md

@@ -18,7 +18,8 @@ ClawMem turns your markdown notes, project docs, and research dumps into persist
 
 - **Surfaces relevant context** on every prompt (context-surfacing hook)
 - **Bootstraps sessions** with your profile, latest handoff, recent decisions, and stale notes
-- **Captures decisions** from session transcripts using a local GGUF observer model
+- **Captures decisions, preferences, milestones, and problems** from session transcripts using a local GGUF observer model
+- **Imports conversation exports** from Claude Code, ChatGPT, Claude.ai, Slack, and plain text via `clawmem mine`
 - **Generates handoffs** at session end so the next session can pick up where you left off
 - **Learns what matters** via a feedback loop that boosts referenced notes and decays unused ones
 - **Guards against prompt injection** in surfaced content
@@ -175,7 +176,7 @@ ClawMem integrates via hooks (`settings.json`) and an MCP stdio server. Hooks ha
 
 ```bash
 clawmem setup hooks    # Install lifecycle hooks (SessionStart, UserPromptSubmit, Stop, PreCompact)
-clawmem setup mcp      # Register MCP server in ~/.claude.json (28 tools)
+clawmem setup mcp      # Register MCP server in ~/.claude.json (31 tools)
 ```
 
 **Automatic (90%):** `context-surfacing` injects relevant memory on every prompt. `postcompact-inject` re-injects state after compaction. `decision-extractor`, `handoff-generator`, `feedback-loop` capture session state on stop.
@@ -202,7 +203,7 @@ Disable OpenClaw's native memory and `memory-lancedb` auto-recall/capture to avo
 openclaw config set agents.defaults.memorySearch.extraPaths "[]"
 ```
 
-**Alternative:** OpenClaw agents can also use ClawMem's MCP server directly (`clawmem setup mcp`), with or without hooks. This gives full access to all 28 MCP tools but bypasses OpenClaw's ContextEngine lifecycle, so you lose token budget awareness, native compaction orchestration, and the `afterTurn()` message pipeline. The ContextEngine plugin is recommended for new OpenClaw setups; MCP is available as an additional or standalone integration.
+**Alternative:** OpenClaw agents can also use ClawMem's MCP server directly (`clawmem setup mcp`), with or without hooks. This gives full access to all 31 MCP tools but bypasses OpenClaw's ContextEngine lifecycle, so you lose token budget awareness, native compaction orchestration, and the `afterTurn()` message pipeline. The ContextEngine plugin is recommended for new OpenClaw setups; MCP is available as an additional or standalone integration.
 
 #### Hermes Agent
 
@@ -309,9 +310,9 @@ ClawMem uses three `llama-server` (llama.cpp) instances for neural inference. Al
 | LLM | 8089 | [qmd-query-expansion-1.7B-q4_k_m](https://huggingface.co/tobil/qmd-query-expansion-1.7B-gguf) | ~2.2GB | Intent classification, query expansion, A-MEM |
 | Reranker | 8090 | [qwen3-reranker-0.6B-Q8_0](https://huggingface.co/ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF) | ~1.3GB | Cross-encoder reranking (query, intent_search) |
 
-The `bin/clawmem` wrapper defaults to `localhost:8088/8089/8090`. If a server is unreachable, ClawMem silently falls back to in-process inference via `node-llama-cpp` (auto-downloads the QMD native models on first use, uses Metal/Vulkan/CPU depending on hardware). With GPU acceleration this is fast; on CPU-only it is significantly slower. ClawMem always works either way, but **if you're running dedicated GPU servers, use [systemd services](docs/guides/systemd-services.md) to ensure they stay up** — otherwise a crashed server silently degrades without warning.
+The `bin/clawmem` wrapper defaults to `localhost:8088/8089/8090`. If a server is unreachable (transport error like ECONNREFUSED/ETIMEDOUT), ClawMem sets a 60-second cooldown and falls back to in-process inference via `node-llama-cpp` (auto-downloads the QMD native models on first use, uses Metal/Vulkan/CPU depending on hardware). HTTP errors (400/500) and user-cancelled requests do not trigger cooldown — the remote server is retried normally on the next call. With GPU acceleration the fallback is fast; on CPU-only it is significantly slower. ClawMem always works either way, but **if you're running dedicated GPU servers, use [systemd services](docs/guides/systemd-services.md) to ensure they stay up**.
 
-To prevent silent fallback and fail fast instead, set `CLAWMEM_NO_LOCAL_MODELS=true`.
+To prevent fallback and fail fast instead, set `CLAWMEM_NO_LOCAL_MODELS=true`.
 
 #### Remote GPU (optional)
 
@@ -472,7 +473,7 @@ llama-server -m Qwen3-Reranker-0.6B-Q8_0.gguf \
 
 ### MCP Server
 
-ClawMem exposes 28 MCP tools via the [Model Context Protocol](https://modelcontextprotocol.io) and an optional HTTP REST API. Any MCP-compatible client or HTTP client can use it.
+ClawMem exposes 31 MCP tools via the [Model Context Protocol](https://modelcontextprotocol.io) and an optional HTTP REST API. Any MCP-compatible client or HTTP client can use it.
 
 **Claude Code (automatic):**
 
@@ -643,6 +644,7 @@ clawmem collection list                         List collections
 clawmem collection remove <name>                Remove a collection
 
 clawmem update [--pull] [--embed]               Incremental re-scan
+clawmem mine <dir> [-c name] [--embed]         Import conversation exports (Claude, ChatGPT, Slack)
 clawmem embed [-f]                              Generate fragment embeddings
 clawmem reindex [--force]                       Full re-index
 clawmem watch                                   File watcher daemon
@@ -676,7 +678,7 @@ clawmem doctor                                  Full health check
 clawmem status                                  Quick index status
 ```
 
-## MCP Tools (28)
+## MCP Tools (31)
 
 Registered by `clawmem setup mcp`. Available to any MCP-compatible client.
 
@@ -713,6 +715,7 @@ Registered by `clawmem setup mcp`. Available to any MCP-compatible client.
 |---|---|
 | `build_graphs` | Build temporal and/or semantic graphs from document corpus |
 | `find_causal_links` | Trace decision chains: "what led to X", "how we got from A to B". Follow up `intent_search` with this tool on a top result to walk the full causal chain. Traverses causes / caused_by / both up to N hops with depth-annotated reasoning. |
+| `kg_query` | Query the SPO knowledge graph: "what does X relate to?", "what was true about X when?". Returns temporal entity-relationship triples with validity windows. Uses entity resolution for lookup. |
 | `memory_evolution_status` | Show how a document's A-MEM metadata evolved over time |
 | `timeline` | Show the temporal neighborhood around a document — what was created/modified before and after it. Progressive disclosure: search → timeline (context) → get (full content). Supports same-collection scoping and session correlation. |
 
@@ -729,6 +732,13 @@ Registered by `clawmem setup mcp`. Available to any MCP-compatible client.
 | `list_vaults` | Show configured vault names and paths. Empty in single-vault mode. |
 | `vault_sync` | Index markdown from a directory into a named vault. Restricted-path validation rejects sensitive directories. |
 
+### Agent Diary
+
+| Tool | Description |
+|---|---|
+| `diary_write` | Write a diary entry. Use for recording important events, decisions, or observations in environments without hook support. Stored as searchable memories. |
+| `diary_read` | Read recent diary entries. Filter by agent name. |
+
 ### Memory Management & Lifecycle
 
 | Tool | Description |
@@ -759,7 +769,7 @@ Hooks installed by `clawmem setup hooks`:
 | `postcompact-inject` | SessionStart | Re-injects authoritative context after compaction: precompact state + recent decisions + antipatterns + vault context (1200 token budget) |
 | `curator-nudge` | SessionStart | Surfaces curator report actions, nudges when report is stale (>7 days) |
 | `precompact-extract` | PreCompact | Extracts decisions, file paths, open questions before auto-compaction → writes `precompact-state.md` to auto-memory |
-| `decision-extractor` | Stop | GGUF observer extracts structured decisions, infers causal links, detects contradictions with prior decisions |
+| `decision-extractor` | Stop | GGUF observer extracts structured observations (decisions, preferences, milestones, problems, bugfixes, features, refactors, discoveries), infers causal links, detects contradictions with prior decisions |
 | `handoff-generator` | Stop | GGUF observer generates rich handoff, regex fallback |
 | `feedback-loop` | Stop | Silently boosts referenced notes, decays unused ones, records co-activation + usage relations between co-referenced docs, tracks utility signals (surfaced vs referenced ratio for lifecycle automation) |
 
@@ -813,15 +823,19 @@ For WHY and ENTITY queries, the search pipeline expands results through the memo
 | Type | Half-life | Baseline | Notes |
 |---|---|---|---|
 | `decision` | ∞ | 0.85 | Never decays |
+| `preference` | ∞ | 0.80 | Never decays — user preferences are durable facts |
 | `hub` | ∞ | 0.80 | Never decays |
+| `antipattern` | ∞ | 0.75 | Never decays — accumulated negative patterns persist |
+| `problem` | 60 days | 0.75 | High priority but resolves over time |
 | `research` | 90 days | 0.70 | |
+| `milestone` | 60 days | 0.70 | Important at the time, fades as project moves forward |
 | `project` | 120 days | 0.65 | |
 | `handoff` | 30 days | 0.60 | Fast decay — most recent matters |
+| `conversation` | 45 days | 0.55 | Imported chat exchanges |
 | `progress` | 45 days | 0.50 | |
 | `note` | 60 days | 0.50 | Default |
-| `antipattern` | ∞ | 0.75 | Never decays — accumulated negative patterns persist |
 
-Content types are inferred from frontmatter or file path patterns. Half-lives extend up to 3× for frequently-accessed memories (access reinforcement, decays over 90 days). Non-durable types (handoff, progress, note, project) lose 5% confidence per week without access (attention decay). Decision/hub/research/antipattern are exempt.
+Content types are inferred from frontmatter or file path patterns. Half-lives extend up to 3× for frequently-accessed memories (access reinforcement, decays over 90 days). Non-durable types (handoff, progress, conversation, note, project) lose 5% confidence per week without access (attention decay). Decision/preference/hub/research/antipattern are exempt.
 
 **Quality scoring:** Each document gets a `quality_score` (0.0–1.0) computed during indexing based on length, structure (headings, lists), decision/correction keywords, and frontmatter richness. Applied as `qualityMultiplier = 0.7 + 0.6 × qualityScore` (range: 0.7× penalty to 1.3× boost).
 
@@ -868,7 +882,7 @@ Documents are split into semantic fragments (sections, lists, code blocks, front
 
 ### Local Observer Agent
 
-Uses the LLM server (shared with query expansion and intent classification) to extract structured observations from session transcripts: type, title, facts, narrative, concepts, files read/modified. Falls back to regex patterns if the model is unavailable.
+Uses the LLM server (shared with query expansion and intent classification) to extract structured observations from session transcripts. Observation types: `decision`, `bugfix`, `feature`, `refactor`, `discovery`, `change`, `preference`, `milestone`, `problem`. Each observation includes title, facts, narrative, concepts, and files read/modified. Preferences, milestones, and problems get first-class content_type treatment with dedicated confidence baselines and half-lives instead of being flattened to generic "observation". Falls back to regex patterns if the model is unavailable.
 
 ### User Profile
 
@@ -943,7 +957,7 @@ title: "Document Title"
 tags: [tag1, tag2]
 domain: "infrastructure"
 workstream: "project-name"
-content_type: "decision"   # decision|hub|research|project|handoff|progress|note
+content_type: "decision"   # decision|preference|hub|research|project|handoff|conversation|progress|note
 review_by: "2026-03-01"
 ---
 ```
@@ -1106,6 +1120,7 @@ Built on the shoulders of:
 - [Hermes Agent](https://github.com/NousResearch/hermes-agent) — MemoryProvider plugin integration, memory nudge system (periodic lifecycle tool prompting)
 - [Hindsight](https://github.com/vectorize-io/hindsight) — entity resolution, MPFP graph traversal, temporal extraction, 3-tier consolidation, observation invalidation, 4-way parallel retrieval
 - [MAGMA](https://arxiv.org/abs/2501.13956) — multi-graph memory agent
+- [MemPalace](https://github.com/milla-jovovich/mempalace) — conversation import patterns, broadened observation taxonomy (preference/milestone/problem), session-bootstrap synthesis
 - [memory-lancedb-pro](https://github.com/CortexReach/memory-lancedb-pro) — retrieval gate, length normalization, MMR diversity, access reinforcement algorithms
 - [OpenViking](https://github.com/volcengine/OpenViking) — query decomposition patterns, collection-scoped retrieval, transaction-safe indexing
 - [QMD](https://github.com/tobi/qmd) — search backend (BM25 + vectors + RRF + reranking)

package/SKILL.md

@@ -242,9 +242,15 @@ Once escalated, route by query type:
 4. Chain tracing -> find_causal_links(docid, direction="both", depth=5)
    Traverses causal edges between _clawmem/agent/observations/ docs.
 
-5. Memory debugging -> memory_evolution_status(docid)
+5. Entity facts -> kg_query(entity, as_of?, direction?)
+   Structured SPO triples with temporal validity. Different from intent_search:
+   - kg_query: "what does ClawMem relate to?" -> returns structured facts (subject-predicate-object)
+   - intent_search: "why did we choose ClawMem?" -> returns documents with causal reasoning
+   Use kg_query for entity lookup, intent_search for causal chains.
 
-6. Temporal context -> timeline(docid, before=5, after=5, same_collection=false)
+6. Memory debugging -> memory_evolution_status(docid)
+
+7. Temporal context -> timeline(docid, before=5, after=5, same_collection=false)
    Shows what was created/modified before and after a document.
    Use after search to understand chronological neighborhood.
 ```
@@ -277,6 +283,9 @@ Once escalated, route by query type:
 | `timeline` | Temporal neighborhood around a document — what was modified before/after. Progressive disclosure: search → timeline → get. Supports same-collection scoping and session correlation. |
 | `list_vaults` | Show configured vault names and paths. Empty in single-vault mode. |
 | `vault_sync` | Index markdown from a directory into a named vault. Restricted-path validation rejects sensitive directories. |
+| `kg_query` | Query SPO knowledge graph for entity relationships with temporal validity. Uses entity resolution. |
+| `diary_write` | Write diary entry. Use proactively in non-hooked environments. Do NOT use in Claude Code. |
+| `diary_read` | Read recent diary entries. Filter by agent name. |
 | `lifecycle_status` | Document lifecycle statistics: active, archived, forgotten, pinned, snoozed counts and policy summary. |
 | `lifecycle_sweep` | Run lifecycle policies: archive stale docs. Defaults to dry_run (preview only). |
 | `lifecycle_restore` | Restore auto-archived documents. Filter by query, collection, or all. Does NOT restore manually forgotten docs. |
@@ -442,12 +451,12 @@ compositeScore = (0.10 x searchScore + 0.70 x recencyScore + 0.20 x confidenceSc
 
 | Content Type | Half-Life | Effect |
 |--------------|-----------|--------|
-| decision, hub | infinity | Never decay |
+| decision, preference, hub | infinity | Never decay |
 | antipattern | infinity | Never decay — accumulated negative patterns persist |
 | project | 120 days | Slow decay |
 | research | 90 days | Moderate decay |
-| note | 60 days | Default |
-| progress | 45 days | Faster decay |
+| problem, milestone, note | 60 days | Default |
+| conversation, progress | 45 days | Faster decay |
 | handoff | 30 days | Fast — recent matters most |
 
 Half-lives extend up to 3x for frequently-accessed memories (access reinforcement decays over 90 days).
@@ -566,6 +575,9 @@ When `decision-extractor` detects a new decision contradicting an old one, the o
 - Do NOT pin everything — pin is for persistent high-priority items.
 - Do NOT forget memories to "clean up" — let confidence decay and contradiction detection handle it.
 - Do NOT run `build_graphs` after every reindex — A-MEM creates per-doc links automatically.
+- Do NOT run `clawmem mine` autonomously — it is a bulk ingestion command. Suggest it to the user when they mention old conversation exports, but let them run it.
+- Do NOT use `diary_write` in Claude Code — hooks capture this automatically. Diary is for non-hooked environments only (Hermes, Gemini, plain MCP).
+- Do NOT use `kg_query` for causal "why" questions — use `intent_search` or `memory_retrieve`. `kg_query` returns structured entity facts (SPO triples), not reasoning chains.
 
 ---
 
@@ -657,6 +669,12 @@ Symptom: reindex --force crashes with UNIQUE constraint
   -> Force deactivates rows but UNIQUE(collection, path) doesn't discriminate by active flag.
   -> Fixed: indexer.ts reactivates inactive rows instead of inserting.
 
+Symptom: `clawmem update` crashes with "Binding expected string, TypedArray, boolean, number, bigint or null"
+  -> YAML frontmatter values like `title: 2023-09-27` or `title: true` are coerced by gray-matter
+     into Date objects or booleans. Bun's SQLite driver rejects these as bind parameters.
+  -> Fixed v0.4.2: `parseDocument()` runtime-checks all frontmatter fields via `str()` helper.
+  -> Affects: title, domain, workstream, content_type, review_by.
+
 Symptom: CLI reindex/update falls back to node-llama-cpp
   -> GPU env vars only in systemd drop-in, not in wrapper script.
   -> Fixed: bin/clawmem wrapper exports CLAWMEM_EMBED_URL/LLM_URL/RERANK_URL defaults.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmem",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "On-device context engine and memory for AI agents. Claude Code and OpenClaw. Hooks + MCP server + hybrid RAG search.",
   "type": "module",
   "bin": {

package/src/clawmem.ts

@@ -235,6 +235,101 @@ async function cmdUpdate(args: string[]) {
   }
 }
 
+async function cmdMine(args: string[]) {
+  const { values, positionals } = parseArgs({
+    args,
+    options: {
+      collection: { type: "string", short: "c" },
+      embed: { type: "boolean", default: false },
+      "dry-run": { type: "boolean", default: false },
+    },
+    allowPositionals: true,
+  });
+
+  const dir = positionals[0];
+  if (!dir) die("Usage: clawmem mine <directory> [-c collection-name] [--embed] [--dry-run]");
+  const absDir = pathResolve(dir);
+  if (!existsSync(absDir)) die(`Directory not found: ${absDir}`);
+
+  const { scanConversationDir, normalizeFile, chunkConversation } = await import("./normalize.ts");
+
+  console.log(`${c.cyan}Scanning for conversation files${c.reset} in ${absDir}`);
+  const files = scanConversationDir(absDir);
+  if (files.length === 0) die("No conversation files found (.json, .jsonl, .txt, .md)");
+  console.log(`  Found ${files.length} candidate files`);
+
+  // Normalize and chunk
+  let totalChunks = 0;
+  let totalConversations = 0;
+  const allChunks: { title: string; body: string; sourcePath: string; chunkIndex: number }[] = [];
+
+  for (const file of files) {
+    const conv = normalizeFile(file);
+    if (!conv) continue;
+    totalConversations++;
+
+    const chunks = chunkConversation(conv);
+    if (chunks.length === 0) continue;
+
+    console.log(`  ${c.green}✓${c.reset} ${conv.source} (${conv.format}, ${conv.messages.length} messages → ${chunks.length} chunks)`);
+    for (const chunk of chunks) {
+      chunk.sourcePath = file.replace(absDir + "/", "");
+    }
+    allChunks.push(...chunks);
+    totalChunks += chunks.length;
+  }
+
+  if (totalConversations === 0) die("No conversation files could be parsed");
+  console.log(`\n${c.bold}Parsed:${c.reset} ${totalConversations} conversations → ${totalChunks} exchange chunks`);
+
+  if (values["dry-run"]) {
+    console.log(`${c.yellow}Dry run — no changes made${c.reset}`);
+    return;
+  }
+
+  // Write chunks as markdown to a staging directory (outside source tree), then index
+  const collectionName = values.collection || "conversations";
+  const { tmpdir } = await import("os");
+  const stagingDir = pathResolve(tmpdir(), `clawmem-mine-${Date.now()}`);
+  mkdirSync(stagingDir, { recursive: true });
+
+  const { rmSync } = await import("fs");
+  try {
+    const writePromises: Promise<number>[] = [];
+    for (const chunk of allChunks) {
+      const safeSource = chunk.sourcePath.replace(/[\/\\]/g, "_").replace(/\.[^.]+$/, "");
+      const filename = `${safeSource}_${String(chunk.chunkIndex).padStart(4, "0")}.md`;
+      const esc = (s: string) => s.replace(/"/g, '\\"');
+      const frontmatter = [
+        "---",
+        `title: "${esc(chunk.title)}"`,
+        `content_type: conversation`,
+        `source: "${esc(chunk.sourcePath)}"`,
+        "---",
+        "",
+        chunk.body,
+      ].join("\n");
+      writePromises.push(Bun.write(pathResolve(stagingDir, filename), frontmatter));
+    }
+    await Promise.all(writePromises);
+
+    // Index through existing pipeline
+    const s = getStore();
+    console.log(`\n${c.cyan}Indexing ${totalChunks} conversation chunks${c.reset} as collection '${collectionName}'`);
+    const stats = await indexCollection(s, collectionName, stagingDir, "**/*.md");
+    console.log(`  ${c.green}+${stats.added}${c.reset} added, ${c.yellow}~${stats.updated}${c.reset} updated, ${c.dim}=${stats.unchanged}${c.reset} unchanged`);
+
+    if (values.embed) {
+      console.log();
+      await cmdEmbed([]);
+    } else {
+      console.log(`\nRun ${c.cyan}clawmem embed${c.reset} to generate embeddings for the imported conversations`);
+    }
+  } finally {
+    rmSync(stagingDir, { recursive: true, force: true });
+  }
+}
+
 async function cmdEmbed(args: string[]) {
   const { values } = parseArgs({
     args,
@@ -1695,6 +1790,9 @@ async function main() {
       case "update":
         await cmdUpdate(subArgs);
         break;
+      case "mine":
+        await cmdMine(subArgs);
+        break;
       case "embed":
         await cmdEmbed(subArgs);
         break;
@@ -1770,6 +1868,9 @@ async function main() {
       case "curate":
         await cmdCurate(subArgs);
         break;
+      case "diary":
+        await cmdDiary(subArgs);
+        break;
       case "help":
       case "--help":
       case "-h":
@@ -2109,6 +2210,99 @@ interface CuratorReport {
   actions: string[];
 }
 
+async function cmdDiary(args: string[]) {
+  const subCmd = args[0];
+  const subArgs = args.slice(1);
+
+  switch (subCmd) {
+    case "write": {
+      const { values, positionals } = parseArgs({
+        args: subArgs,
+        options: {
+          topic: { type: "string", short: "t", default: "general" },
+          agent: { type: "string", short: "a", default: "user" },
+        },
+        allowPositionals: true,
+      });
+
+      const entry = positionals.join(" ");
+      if (!entry) die("Usage: clawmem diary write <entry text> [-t topic] [-a agent-name]");
+
+      const s = getStore();
+      const now = new Date();
+      const dateStr = now.toISOString().slice(0, 10);
+      const timeStr = now.toISOString().slice(11, 19).replace(/:/g, "");
+      const ms = String(now.getMilliseconds()).padStart(3, "0");
+      const diaryPath = `diary/${dateStr}-${timeStr}${ms}-${values.topic}.md`;
+      const body = [
+        "---",
+        `title: "${entry.slice(0, 80).replace(/"/g, '\\"')}"`,
+        `content_type: note`,
+        `tags: [diary, ${values.topic}]`,
+        `domain: "${values.agent}"`,
+        "---",
+        "",
+        entry,
+      ].join("\n");
+
+      const result = s.saveMemory({
+        collection: "_clawmem",
+        path: diaryPath,
+        title: entry.slice(0, 80),
+        body,
+        contentType: "note",
+        confidence: 0.7,
+        semanticPayload: `${diaryPath}::${entry}`,
+      });
+
+      console.log(`${c.green}✓${c.reset} Diary entry saved (${result.action}, doc #${result.docId})`);
+      break;
+    }
+
+    case "read": {
+      const { values } = parseArgs({
+        args: subArgs,
+        options: {
+          last: { type: "string", short: "n", default: "10" },
+          agent: { type: "string", short: "a" },
+        },
+        allowPositionals: false,
+      });
+
+      const limit = parseInt(values.last || "10", 10);
+      const s = getStore();
+
+      const rows = s.db.prepare(`
+        SELECT d.id, d.path, d.title, d.modified_at as modifiedAt, d.domain,
+               c.doc as body
+        FROM documents d
+        JOIN content c ON c.hash = d.hash
+        WHERE d.active = 1 AND d.collection = '_clawmem' AND d.path LIKE 'diary/%'
+        ${values.agent ? "AND d.domain = ?" : ""}
+        ORDER BY d.modified_at DESC
+        LIMIT ?
+      `).all(...(values.agent ? [values.agent, limit] : [limit])) as any[];
+
+      if (rows.length === 0) {
+        console.log("No diary entries found.");
+        break;
+      }
+
+      console.log(`${c.bold}Diary${c.reset} (${rows.length} entries)\n`);
+      for (const row of rows) {
+        const agent = row.domain ? ` [${row.domain}]` : "";
+        console.log(`${c.dim}${row.modifiedAt.slice(0, 16)}${c.reset}${agent} ${row.title}`);
+      }
+      break;
+    }
+
+    default:
+      console.log(`Usage:
+  clawmem diary write <entry> [-t topic] [-a agent]   Write diary entry
+  clawmem diary read [-n limit] [-a agent]            Read recent entries`);
+  }
+}
+
 async function cmdCurate(_args: string[]) {
   const s = getStore();
   const report: CuratorReport = {
@@ -2289,6 +2483,7 @@ ${c.bold}Setup:${c.reset}
 
 ${c.bold}Indexing:${c.reset}
   clawmem update [--pull] [--embed]    Re-scan collections (--embed auto-embeds)
+  clawmem mine <dir> [-c name] [--embed]  Import conversation exports (Claude, ChatGPT, Slack)
   clawmem embed [-f]                   Generate fragment embeddings
   clawmem reindex [--force] [--enrich]  Full re-index (--enrich: run entity extraction + links on all docs)
   clawmem watch                        File watcher daemon
@@ -2323,6 +2518,8 @@ ${c.bold}Intelligence:${c.reset}
   clawmem reflect [days]               Cross-session pattern analysis
   clawmem consolidate [--dry-run]      Merge duplicate low-confidence docs
   clawmem curate                       Automated maintenance (health, sweep, dedup, hygiene)
+  clawmem diary write <entry> [-t topic]  Write a diary entry (for non-hooked environments)
+  clawmem diary read [-n N] [-a agent]    Read recent diary entries
 
 ${c.bold}Integration:${c.reset}
   clawmem mcp                          Start stdio MCP server