clawmem 0.5.0 → 0.6.0

package/AGENTS.md

@@ -250,7 +250,7 @@ ClawMem hooks handle ~90% of retrieval automatically. Agent-initiated MCP calls
 | `postcompact-inject` | SessionStart (compact) | 1200 tokens | re-injects authoritative context after compaction: precompact state (600) + recent decisions (400) + antipatterns (150) + vault context (200) → `<vault-postcompact>` |
 | `curator-nudge` | SessionStart | 200 tokens | surfaces curator report actions, nudges when report is stale (>7 days) |
 | `precompact-extract` | PreCompact | — | extracts decisions, file paths, open questions → writes `precompact-state.md` to auto-memory. Query-aware decision ranking. Reindexes auto-memory collection. |
-| `decision-extractor` | Stop | — | LLM extracts observations → `_clawmem/agent/observations/`, infers causal links, detects contradictions with prior decisions |
+| `decision-extractor` | Stop | — | LLM extracts observations → `_clawmem/agent/observations/`, infers causal links, detects contradictions, extracts SPO triples from decision/preference/milestone/problem facts. Background consolidation worker synthesizes deductive observations from related facts (Phase 3, every ~15 min). |
 | `handoff-generator` | Stop | — | LLM summarizes session → `_clawmem/agent/handoffs/` |
 | `feedback-loop` | Stop | — | tracks referenced notes → boosts confidence, records usage relations + co-activations between co-referenced docs, tracks utility signals (surfaced vs referenced ratio for lifecycle automation) |
 
@@ -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
 
@@ -355,6 +364,8 @@ Pin, snooze, and forget are **manual MCP tools** — not automated. The agent sh
 - 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)
 
@@ -436,7 +447,7 @@ compositeScore = (0.10 × searchScore + 0.70 × recencyScore + 0.20 × confidenc
 
 | Content Type | Half-Life | Effect |
 |--------------|-----------|--------|
-| decision, preference, hub | ∞ | Never decay |
+| decision, deductive, preference, hub | ∞ | Never decay |
 | antipattern | ∞ | Never decay — accumulated negative patterns persist |
 | project | 120 days | Slow decay |
 | research | 90 days | Moderate decay |
@@ -445,7 +456,7 @@ compositeScore = (0.10 × searchScore + 0.70 × recencyScore + 0.20 × confidenc
 | 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, conversation, note, project) lose 5% confidence per week without access. Decision/preference/hub/research/antipattern are exempt.
+Attention decay: non-durable types (handoff, progress, conversation, note, project) lose 5% confidence per week without access. Decision/deductive/preference/hub/research/antipattern are exempt.
 
 ## Indexing & Graph Building
 
@@ -488,6 +499,7 @@ The `memory_relations` table is populated by multiple independent sources:
 | `buildSemanticGraph()` | semantic | `build_graphs` MCP tool (manual) | Pure cosine similarity. PK collision: `INSERT OR IGNORE` means A-MEM semantic edges take precedence if they exist first. |
 | Entity co-occurrence graph | entity | A-MEM enrichment (indexing) | LLM entity extraction → quality filters (title/length/blocklist/location validation) → type-agnostic canonical resolution within compatibility buckets (person, org, location, tech=project/service/tool/concept) → `entity_mentions` + `entity_cooccurrences` tables. Entity edges use IDF-based specificity scoring. Feeds ENTITY intent queries and MPFP `[entity, semantic]` patterns. |
 | `consolidated_observations` | supporting | Consolidation worker (background) | 3-tier consolidation: facts → observations → mental models. Observations track `proof_count`, `trend` (STABLE/STRENGTHENING/WEAKENING/STALE), and source links. |
+| Deductive synthesis | supporting | Consolidation worker Phase 3 (background, every ~15 min) | Combines 2-3 related recent observations (decision/preference/milestone/problem, last 7 days) into `content_type='deductive'` documents with `source_doc_ids` provenance. First-class searchable docs with ∞ half-life. |
 
 **Edge collision:** Both `generateMemoryLinks()` and `buildSemanticGraph()` insert `relation_type='semantic'`. PK is `(source_id, target_id, relation_type)` — first writer wins.
 
@@ -564,6 +576,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

@@ -250,7 +250,7 @@ ClawMem hooks handle ~90% of retrieval automatically. Agent-initiated MCP calls
 | `postcompact-inject` | SessionStart (compact) | 1200 tokens | re-injects authoritative context after compaction: precompact state (600) + recent decisions (400) + antipatterns (150) + vault context (200) → `<vault-postcompact>` |
 | `curator-nudge` | SessionStart | 200 tokens | surfaces curator report actions, nudges when report is stale (>7 days) |
 | `precompact-extract` | PreCompact | — | extracts decisions, file paths, open questions → writes `precompact-state.md` to auto-memory. Query-aware decision ranking. Reindexes auto-memory collection. |
-| `decision-extractor` | Stop | — | LLM extracts observations → `_clawmem/agent/observations/`, infers causal links, detects contradictions with prior decisions |
+| `decision-extractor` | Stop | — | LLM extracts observations → `_clawmem/agent/observations/`, infers causal links, detects contradictions, extracts SPO triples from decision/preference/milestone/problem facts. Background consolidation worker synthesizes deductive observations from related facts (Phase 3, every ~15 min). |
 | `handoff-generator` | Stop | — | LLM summarizes session → `_clawmem/agent/handoffs/` |
 | `feedback-loop` | Stop | — | tracks referenced notes → boosts confidence, records usage relations + co-activations between co-referenced docs, tracks utility signals (surfaced vs referenced ratio for lifecycle automation) |
 
@@ -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
 
@@ -355,6 +364,8 @@ Pin, snooze, and forget are **manual MCP tools** — not automated. The agent sh
 - 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)
 
@@ -436,7 +447,7 @@ compositeScore = (0.10 × searchScore + 0.70 × recencyScore + 0.20 × confidenc
 
 | Content Type | Half-Life | Effect |
 |--------------|-----------|--------|
-| decision, preference, hub | ∞ | Never decay |
+| decision, deductive, preference, hub | ∞ | Never decay |
 | antipattern | ∞ | Never decay — accumulated negative patterns persist |
 | project | 120 days | Slow decay |
 | research | 90 days | Moderate decay |
@@ -445,7 +456,7 @@ compositeScore = (0.10 × searchScore + 0.70 × recencyScore + 0.20 × confidenc
 | 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, conversation, note, project) lose 5% confidence per week without access. Decision/preference/hub/research/antipattern are exempt.
+Attention decay: non-durable types (handoff, progress, conversation, note, project) lose 5% confidence per week without access. Decision/deductive/preference/hub/research/antipattern are exempt.
 
 ## Indexing & Graph Building
 
@@ -488,6 +499,7 @@ The `memory_relations` table is populated by multiple independent sources:
 | `buildSemanticGraph()` | semantic | `build_graphs` MCP tool (manual) | Pure cosine similarity. PK collision: `INSERT OR IGNORE` means A-MEM semantic edges take precedence if they exist first. |
 | Entity co-occurrence graph | entity | A-MEM enrichment (indexing) | LLM entity extraction → quality filters (title/length/blocklist/location validation) → type-agnostic canonical resolution within compatibility buckets (person, org, location, tech=project/service/tool/concept) → `entity_mentions` + `entity_cooccurrences` tables. Entity edges use IDF-based specificity scoring. Feeds ENTITY intent queries and MPFP `[entity, semantic]` patterns. |
 | `consolidated_observations` | supporting | Consolidation worker (background) | 3-tier consolidation: facts → observations → mental models. Observations track `proof_count`, `trend` (STABLE/STRENGTHENING/WEAKENING/STALE), and source links. |
+| Deductive synthesis | supporting | Consolidation worker Phase 3 (background, every ~15 min) | Combines 2-3 related recent observations (decision/preference/milestone/problem, last 7 days) into `content_type='deductive'` documents with `source_doc_ids` provenance. First-class searchable docs with ∞ half-life. |
 
 **Edge collision:** Both `generateMemoryLinks()` and `buildSemanticGraph()` insert `relation_type='semantic'`. PK is `(source_id, target_id, relation_type)` — first writer wins.
 
@@ -564,6 +576,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

@@ -176,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.
@@ -203,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
 
@@ -310,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)
 
@@ -473,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):**
 
@@ -678,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.
 
@@ -715,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. |
 
@@ -731,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 |
@@ -815,6 +823,7 @@ For WHY and ENTITY queries, the search pipeline expands results through the memo
 | Type | Half-life | Baseline | Notes |
 |---|---|---|---|
 | `decision` | ∞ | 0.85 | Never decays |
+| `deductive` | ∞ | 0.85 | Never decays — cross-session derived insights with source provenance |
 | `preference` | ∞ | 0.80 | Never decays — user preferences are durable facts |
 | `hub` | ∞ | 0.80 | Never decays |
 | `antipattern` | ∞ | 0.75 | Never decays — accumulated negative patterns persist |
@@ -827,7 +836,7 @@ For WHY and ENTITY queries, the search pipeline expands results through the memo
 | `progress` | 45 days | 0.50 | |
 | `note` | 60 days | 0.50 | Default |
 
-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.
+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/deductive/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).
 
@@ -1111,7 +1120,9 @@ Built on the shoulders of:
 - [Engram](https://github.com/Gentleman-Programming/engram) — observation dedup window, topic-key upsert pattern, temporal timeline navigation, duplicate metadata scoring signals
 - [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
+- [Honcho](https://github.com/plastic-labs/honcho) — deductive observation synthesis patterns, surprisal-based anomaly scoring concept, embed-state self-healing, retrieval separation (raw vs derived)
 - [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,7 +451,7 @@ compositeScore = (0.10 x searchScore + 0.70 x recencyScore + 0.20 x confidenceSc
 
 | Content Type | Half-Life | Effect |
 |--------------|-----------|--------|
-| decision, preference, hub | infinity | Never decay |
+| decision, deductive, preference, hub | infinity | Never decay |
 | antipattern | infinity | Never decay — accumulated negative patterns persist |
 | project | 120 days | Slow decay |
 | research | 90 days | Moderate decay |
@@ -567,6 +576,8 @@ When `decision-extractor` detects a new decision contradicting an old one, the o
 - 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.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmem",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "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

@@ -410,6 +410,9 @@ async function cmdEmbed(args: string[]) {
 
     const fragments = splitDocument(body, frontmatter);
     const docStart = Date.now();
+    const prevTotalFragments = totalFragments;
+    const prevFailedFragments = failedFragments;
+    let seq0Succeeded = false;
     console.error(`  [${docIdx + 1}/${hashes.length}] ${basename(path)} (${fragments.length} frags, ${body.length} chars)`);
 
     if (isCloudEmbed) {
@@ -463,6 +466,7 @@ async function cmdEmbed(args: string[]) {
                 result.model, new Date().toISOString(), frag.type, frag.label ?? undefined, canId
               );
               totalFragments++;
+              if (seq === 0) seq0Succeeded = true;
             } else {
               failedFragments++;
             }
@@ -491,6 +495,7 @@ async function cmdEmbed(args: string[]) {
               result.model, new Date().toISOString(), frag.type, frag.label ?? undefined, canId
             );
             totalFragments++;
+            if (seq === 0) seq0Succeeded = true;
             if (seq === 0 || (seq + 1) % 5 === 0 || seq === fragments.length - 1) {
               console.error(`    frag ${seq + 1}/${fragments.length} (${frag.type}) ${fragMs}ms [${text.length} chars]`);
             }
@@ -505,6 +510,18 @@ async function cmdEmbed(args: string[]) {
       }
     }
 
+    // Track embed state per document — seq=0 (primary) must succeed for synced status
+    const docFragsOk = totalFragments - prevTotalFragments;
+    const docFragsFail = failedFragments - prevFailedFragments;
+    if (seq0Succeeded) {
+      s.markEmbedSynced(hash);
+    } else if (docFragsOk === 0 && docFragsFail > 0) {
+      s.markEmbedFailed(hash, "all fragments failed");
+    } else {
+      // seq=0 failed but some later fragments succeeded — mark failed so seq=0 gets retried
+      s.markEmbedFailed(hash, "primary fragment (seq=0) failed");
+    }
+
     embedded++;
     const docMs = Date.now() - docStart;
     const elapsed = ((Date.now() - batchStart) / 1000).toFixed(0);
@@ -1868,6 +1885,9 @@ async function main() {
       case "curate":
         await cmdCurate(subArgs);
         break;
+      case "diary":
+        await cmdDiary(subArgs);
+        break;
       case "help":
       case "--help":
       case "-h":
@@ -2207,6 +2227,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 = {
@@ -2422,6 +2535,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