clawmem 0.8.2 → 0.8.3

package/README.md

@@ -47,82 +47,7 @@ ClawMem turns your markdown notes, project docs, and research dumps into persist
 
 Runs fully local with no API keys and no cloud services. Integrates via Claude Code hooks and MCP tools, as an OpenClaw ContextEngine plugin, or as a Hermes Agent MemoryProvider plugin. All modes share the same vault for cross-runtime memory. Works with any MCP-compatible client.
 
-### v0.2.0 Enhancements
-
-- **Entity resolution + co-occurrence graph** — LLM entity extraction with quality filters, type-agnostic canonical resolution within [compatibility buckets](docs/internals/entity-resolution.md) (extensible type vocabulary), IDF-based entity edge scoring, co-occurrence tracking, entity graph traversal for ENTITY intent queries
-- **MPFP graph retrieval** — Multi-Path Fact Propagation with meta-path patterns per intent, hop-synchronized edge cache, Forward Push with α=0.15 teleport probability. Replaces single-beam traversal for causal/entity/temporal queries.
-- **Temporal query extraction** — regex-based date range extraction from natural language queries ("last week", "March 2026"), wired as WHERE filters into BM25 and vector search
-- **4-way parallel retrieval** — temporal proximity and entity graph channels added as parallel RRF legs in `query` tool (Tier 3 only), alongside existing BM25 + vector channels
-- **3-tier consolidation** — facts to observations (auto-generated, with proof_count and trend enum) to mental models. Background worker synthesizes clusters of related observations into consolidated patterns.
-- **Observation invalidation** — soft invalidation (invalidated_at/invalidated_by/superseded_by columns). Observations with confidence ≤ 0.2 after contradiction are filtered from search results.
-- **Memory nudge** — periodic ephemeral `<vault-nudge>` injection prompting lifecycle tool use after N turns of inactivity. Configurable via `CLAWMEM_NUDGE_INTERVAL`.
-
-### v0.7.1 Safety Release
-
-Five independent safety gates around the consolidation pipeline and context surfacing, aimed at preventing contamination, cross-entity merges, and unchecked contradictions from landing in the vault. Every extraction ships with full unit + integration test coverage (+158 tests on top of the v0.7.0 baseline). See [consolidation safety](docs/concepts/architecture.md#consolidation-safety-v071) for the architectural walkthrough.
-
-- **Taxonomy cleanup** — standardized on the A-MEM `contradicts` (plural) convention across the entire codebase, eliminating silent query misses on the legacy singular form
-- **Name-aware merge safety** — the Phase 2 consolidation worker gate extracts entity anchors (via `entity_mentions`, with lexical proper-noun fallback) and runs dual-threshold normalized 3-gram cosine similarity before merging similar observations. Cross-entity merges are hard-rejected when anchor sets differ materially, preventing context bleed where "Alice decided X" merges into "Bob decided X". Thresholds are env-overridable (`CLAWMEM_MERGE_SCORE_NORMAL`=0.93, `_STRICT`=0.98). Dry-run mode via `CLAWMEM_MERGE_GUARD_DRY_RUN` for calibration.
-- **Contradiction-aware merge gate** — after the name-aware gate passes, a deterministic heuristic (negation asymmetry, number/date mismatch) plus an LLM check detect contradictory merges. Blocked merges route to `link` policy (insert new row + `contradicts` edge, default) or `supersede` policy (mark old row `status='inactive'`). Configurable via `CLAWMEM_CONTRADICTION_POLICY` and `CLAWMEM_CONTRADICTION_MIN_CONFIDENCE`. Phase 3 deductive synthesis applies the same gate to deductive dedupe matches.
-- **Anti-contamination deductive synthesis** — every Phase 3 draft runs through a three-layer validator: deterministic pre-checks (empty conclusion, invalid source_indices, pool-only entity contamination via `entity_mentions`) + LLM validator (fail-open with `validatorFallbackAccepts` counter) + dedupe. Per-reason rejection stats exposed via `DeductiveSynthesisStats` so Phase 3 yield can be diagnosed without enabling extra logging.
-- **Context instruction + relationship snippets** — `context-surfacing` now always prepends an `<instruction>` block framing the surfaced facts as background knowledge the model already holds, and appends an optional `<relationships>` block listing memory-graph edges where BOTH endpoints are in the surfaced doc set. The relationships block is the first thing dropped when the payload would overflow `CLAWMEM_PROFILE`'s token budget, preserving facts-first behaviour while giving the model graph-level reasoning hooks directly in-prompt.
-
-### v0.7.2 Post-Import Conversation Synthesis
-
-Opt-in LLM pass that runs **after** `clawmem mine` finishes indexing an imported collection. Operates on the freshly imported `content_type='conversation'` documents and extracts structured knowledge facts (decisions / preferences / milestones / problems) plus cross-fact relations, writing each fact as a first-class searchable document alongside the raw conversation exchanges. See [post-import synthesis](docs/concepts/architecture.md#post-import-conversation-synthesis-v072) for the architectural walkthrough.
-
-- **New CLI flag** — `clawmem mine <dir> --synthesize [--synthesis-max-docs N]`. Off by default. When omitted, existing mine behaviour is byte-identical to v0.7.1.
-- **Two-pass pipeline** — Pass 1 extracts facts per conversation via the existing LLM, saves each via dedup-aware `saveMemory`, and populates a local alias map. Pass 2 resolves cross-fact links against the local map first, falling back to collection-scoped SQL lookup. Forward references (link to a fact extracted later in the same run) are resolved correctly.
-- **Idempotent reruns** — synthesized fact paths are a pure function of `(sourceDocId, slug(title), short sha256(normalizedTitle))`, so reruns over the same conversation batch hit the `saveMemory` update branch instead of creating parallel rows. Same-slug collisions are disambiguated by the stable hash suffix, not encounter order.
-- **Fail-closed link resolution** — when two different facts claim the same normalized title or alias, the resolver treats the link as ambiguous and counts it unresolved. Pre-existing docs with duplicate titles in the collection do not silently bind either.
-- **Weight-monotonic relation upsert** — `memory_relations` insert uses `ON CONFLICT DO UPDATE SET weight = MAX(weight, excluded.weight)`, which is idempotent on equal-weight reruns but still accepts stronger later evidence without double-counting.
-- **Non-fatal failure model** — any LLM failure, JSON parse error, saveMemory collision, or relation insert error is counted and logged, never re-thrown. Synthesis failure after `indexCollection` commits does not roll back the mine import.
-- **Split operator counters** — `llmFailures` counts actual LLM path failures (null, thrown, non-array JSON), while `docsWithNoFacts` counts docs where the LLM responded validly but returned zero structured facts. Previously these were conflated as `nullCalls`.
-
-Adds +63 tests (46 unit + 5 integration + 12 regression) on top of the v0.7.1 baseline.
-
-### v0.8.0 Quiet-Window Heavy Maintenance Lane
-
-A second, longer-interval consolidation worker that keeps Phase 2 + Phase 3 running on large vaults without starving interactive sessions. Off by default — set `CLAWMEM_HEAVY_LANE=true` to enable. The existing 5-minute light-lane worker is unchanged. See [heavy maintenance lane](docs/concepts/architecture.md#heavy-maintenance-lane-v080) for the architectural walkthrough.
-
-- **Quiet-window gating** — the heavy lane only runs inside the hours set by `CLAWMEM_HEAVY_LANE_WINDOW_START` / `CLAWMEM_HEAVY_LANE_WINDOW_END` (0-23). Supports midnight wraparound (e.g., 22→6). Null on either bound means "always in window".
-- **Query-rate gating via `context_usage`** — counts hook injections in the last 10 minutes and skips the tick when the rate exceeds `CLAWMEM_HEAVY_LANE_MAX_USAGES` (default 30). No new `query_activity` table; reuses v0.7.0 telemetry.
-- **DB-backed worker leases** — exclusivity enforced via a new `worker_leases` table with atomic `INSERT ... ON CONFLICT DO UPDATE ... WHERE expires_at <= ?` acquisition, random 16-byte fencing tokens, and TTL reclaim. Safe under multi-process contention; any SQLite error translates to a `lease_unavailable` skip rather than a thrown exception.
-- **Stale-first selection** — Phase 2 and Phase 3 reorder their candidate sets by `COALESCE(recall_stats.last_recalled_at, documents.last_accessed_at, documents.modified_at) ASC` so long-unseen docs bubble up first. Empty `recall_stats` falls through to access-time without erroring.
-- **Optional surprisal selector** — `CLAWMEM_HEAVY_LANE_SURPRISAL=true` plumbs k-NN anomaly-ranked doc ids (via the existing `computeSurprisalScores`) into Phase 2 as an explicit `candidateIds` filter. Degrades to stale-first on vaults without embeddings and logs `selector: 'surprisal-fallback-stale'` in the journal.
-- **`maintenance_runs` journal** — every scheduled attempt writes a row: `status` (`started`/`completed`/`failed`/`skipped`), `reason` for skips, selected/processed/created/null_call counts, and a `metrics_json` payload with selector type and full `DeductiveSynthesisStats` breakdown. Operators can reconstruct any lane decision without reading worker logs.
-- **Force-enforce merge gate** — the heavy lane passes `guarded: true` to `consolidateObservations`, which overrides `CLAWMEM_MERGE_GUARD_DRY_RUN` inside `findSimilarConsolidation` so experimenting operators cannot weaken heavy-lane enforcement via env flag.
-
-Adds +56 tests (13 worker-lease + 35 maintenance unit + 8 maintenance integration) on top of the v0.7.2 baseline.
-
-### v0.8.1 Multi-Turn Prior-Query Lookback
-
-`context-surfacing` now builds its retrieval query from the current prompt plus up to two recent same-session prior prompts, so a short follow-up turn ("do the same for X", "explain the rationale") can still inherit the vocabulary of earlier turns. The raw prompt is persisted in a new nullable `context_usage.query_text` column so future hook ticks can reconstitute the multi-turn query from the DB. See [multi-turn lookback](docs/concepts/architecture.md#multi-turn-prior-query-lookback-v081) for the full walkthrough.
-
-- **Additive schema migration** — new nullable `query_text TEXT` column on `context_usage`, guarded by `PRAGMA table_info`. Pre-v0.8.1 stores get the column added on first open; ad-hoc stores that skip the migration path degrade transparently via a feature-detect WeakMap so `insertUsageFn` never writes a column that doesn't exist.
-- **Discovery path only** — the multi-turn query feeds vector search, BM25, and query expansion. Cross-encoder reranking continues to use the RAW current prompt so relevance scoring is not diluted by older turns, and composite scoring / snippet extraction / dedupe / routing-hint detection all remain on the raw prompt as well.
-- **Privacy-conscious persistence split** — gated skip paths (slash commands, `MIN_PROMPT_LENGTH`, `shouldSkipRetrieval`, heartbeat dedupe) do NOT persist their raw text because those turns are not meaningful user questions and carry a higher sensitivity profile. Post-retrieval empty paths (empty result set, threshold blocked, budget blocked) DO persist so a follow-up turn can still inherit the intent even when the current turn surfaced nothing.
-- **Current-first truncation** — the combined query is clamped to 2000 chars with the current prompt preserved verbatim at the head. Older priors are dropped first when the budget runs out. If the current prompt alone already exceeds the cap, priors are omitted entirely and the current prompt is truncated.
-- **SQL-level self-match guard** — duplicate submits of the same prompt are filtered out of the lookback SELECT via `AND query_text != ?` so a retry burst cannot eat into the 2-prior budget and leave the lookback window underfilled.
-- **10-minute max age, session-scoped** — priors older than 10 minutes or from a different `session_id` are invisible to the lookback. All fallback paths (missing column, DB error, no matching rows) return the current prompt unchanged — the hook never throws on lookback failures.
-
-Adds +27 tests (22 unit + 5 integration) on top of the v0.8.0 baseline.
-
-### v0.8.2 Dual-Host Worker Architecture
-
-Both maintenance lanes can now be hosted by the long-lived `clawmem watch` watcher service in addition to the existing per-session `clawmem mcp` host. This makes the systemd-managed watcher the canonical 24/7 home for the v0.8.0 heavy maintenance lane — its quiet-window logic finally sees a live worker at the configured hours regardless of whether any Claude Code session is open. The light consolidation lane (Phase 1 backfill + Phase 2 merge + Phase 3 deductive synthesis + Phase 4 recall stats) now also acquires its own DB-backed `worker_leases` row before each tick, symmetric with the heavy lane's existing exclusivity, so multiple host processes against the same vault cannot race on Phase 2 merges or Phase 3 deductive writes.
-
-- **Light-lane worker lease** — `runConsolidationTick` wraps every tick (Phase 1 → 4) in `withWorkerLease` against a new `light-consolidation` worker name with a 10-minute TTL. Two host processes (e.g. one watcher service + one per-session stdio MCP) cannot both consolidate the same near-duplicate observations or both INSERT a duplicate row into `consolidated_observations`. Phase 1 enrichment is also serialized — overkill for cost but cleaner for symmetry. The in-process `isRunning` reentrancy guard remains the cheap first defense before the SQLite lease round-trip.
-- **`cmdWatch` hosts both workers** — `clawmem watch` honors the same `CLAWMEM_ENABLE_CONSOLIDATION` and `CLAWMEM_HEAVY_LANE` env-var gates as `cmdMcp`. Off by default. Mirror the existing systemd unit (or your wrapper `.env`) to opt in. The recommended deployment for v0.8.2+ is to set both env vars on `clawmem-watcher.service` and leave `cmdMcp` unset, so the heavy lane has a continuously available host independent of Claude Code session lifecycle.
-- **`cmdMcp` is now a fallback host with a heavy-lane warning** — `cmdMcp` retains the same env-var gates so non-watcher deployments (e.g. macOS users running everything via Claude Code launchd) keep working unchanged. When `CLAWMEM_HEAVY_LANE=true` is set on a stdio MCP host, `cmdMcp` emits a one-line warning to stderr advising operators to move heavy-lane hosting to `clawmem watch` instead.
-- **Async drain on shutdown** — both worker stop helpers (`stopConsolidationWorker` and the closure returned by `startHeavyMaintenanceWorker`) are now `async`, clearing their `setInterval` AND polling their in-flight running flag until any mid-tick worker drains. This guarantees the worker's `withWorkerLease` finally block runs against a still-open store, so the lease is released cleanly instead of leaking until TTL expiry. Bounded waits (15s light, 30s heavy) prevent a stuck tick from wedging shutdown indefinitely; the next process reclaims any stranded lease atomically.
-- **Signal handlers registered before worker startup** — both `cmdWatch` and `cmdMcp` now register their `SIGINT`/`SIGTERM` handlers BEFORE any worker initialization. A signal arriving in the brief window between worker startup and handler registration would otherwise terminate the host via the default signal action (exit 143) and skip the async drain entirely.
-- **Subprocess smoke test** — new `tests/integration/cmdwatch-workers.integration.test.ts` spawns `bun src/clawmem.ts watch` against a temp vault with short worker intervals, exercises the env-var gates, exercises a real heavy-lane tick (slow path, ~35s), and asserts the lease is released cleanly on `SIGTERM`.
-- **Bug fix: removed dead skill-vault watcher block from `clawmem.ts cmdWatch()`** — a try/catch wrapped block had been silently destructuring `getSkillContentRoot` from `./config.ts`, but that helper is forge-internal and was never exported in public ClawMem. The runtime catch swallowed the failure so it had no observable effect, but TypeScript flagged a static `TS2339` error on the destructure. v0.8.2 removes the dead code path. No behavior change for public users.
-
-Adds +15 tests (9 light-lane lease unit + 5 cmdWatch fast subprocess + 1 cmdWatch slow subprocess) on top of the v0.8.1 baseline.
-
-For operational guidance — enabling the workers via systemd drop-in, tuning intervals to your usage pattern, monitoring queries, and rollback steps — see [docs/guides/systemd-services.md](docs/guides/systemd-services.md#background-maintenance-workers-v082).
+Full version history is in [RELEASE_NOTES.md](RELEASE_NOTES.md). Upgrade instructions for existing vaults are in [docs/guides/upgrading.md](docs/guides/upgrading.md).
 
 ## Architecture
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmem",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "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/entity.ts

@@ -161,6 +161,53 @@ function makeEntityId(name: string, type: string, vault: string = 'default'): st
   return `${vault}:${type}:${normalized}`;
 }
 
+// =============================================================================
+// Entity Cap (content-type-aware, §1.5 v0.8.3)
+// =============================================================================
+
+/**
+ * Per-content-type entity cap applied to LLM extraction output.
+ *
+ * Long-form content (research dumps, conversation synthesis, hub/index docs)
+ * legitimately mentions more distinct entities than short decision records or
+ * handoff notes. A flat cap of 10 silently dropped real entities on long-form
+ * documents. This map lets each content type keep its full entity set up to a
+ * type-appropriate ceiling, while short types stay tight to suppress LLM noise.
+ *
+ * Unknown or untyped documents fall through to the default cap of 10 (matches
+ * pre-v0.8.3 behavior — backward compatible for any caller that doesn't pass
+ * a contentType).
+ */
+const ENTITY_CAP_BY_TYPE: Record<string, number> = {
+  research: 15,       // long-form research dumps
+  hub: 12,            // architecture docs, indexes
+  conversation: 12,   // synthesized conversation exports
+  decision: 8,        // short decision records
+  deductive: 8,       // inferred observations
+  note: 8,            // session notes
+  handoff: 8,         // session handoffs
+  progress: 8,        // progress logs
+  project: 10,        // generic project content
+};
+
+/**
+ * Return the entity cap for a given content type. Falls back to 10 for
+ * undefined or unknown types (pre-v0.8.3 behavior).
+ *
+ * Input is trimmed + lowercased before lookup so values from hand-authored
+ * frontmatter or older imported docs (e.g. "Research", " conversation ") map
+ * cleanly to the canonical lowercase keys in `ENTITY_CAP_BY_TYPE`. The DB
+ * `documents.content_type` column is not normalized at the write boundary,
+ * so normalization has to happen here to avoid silent fall-through to the
+ * default cap of 10.
+ */
+export function entityCapForContentType(contentType?: string): number {
+  if (!contentType) return 10;
+  const key = contentType.trim().toLowerCase();
+  if (!key) return 10;
+  return ENTITY_CAP_BY_TYPE[key] ?? 10;
+}
+
 // =============================================================================
 // Entity Extraction (LLM-based)
 // =============================================================================
@@ -168,14 +215,25 @@ function makeEntityId(name: string, type: string, vault: string = 'default'): st
 /**
  * Extract named entities from document content using LLM.
  * Returns a list of (name, type) pairs.
+ *
+ * @param contentType Optional document content_type. When provided, caps the
+ *   returned entity list using `entityCapForContentType`. When omitted, uses
+ *   the default cap of 10 (backward compatible).
  */
 export async function extractEntities(
   llm: LLM,
   title: string,
-  content: string
+  content: string,
+  contentType?: string
 ): Promise<ExtractedEntity[]> {
   const truncated = content.slice(0, 2000);
 
+  // v0.8.3 (§1.5): compute the cap up front so we can thread it into BOTH
+  // the prompt ("0-N entities") and the post-LLM slice. Without the dynamic
+  // prompt, a compliant model stops at the hardcoded 10 even when we'd
+  // accept 15 — the slice becomes a no-op and §1.5 is only half-effective.
+  const cap = entityCapForContentType(contentType);
+
   const prompt = `Extract named entities from this document. Include people, projects, services, tools, organizations, and specific technical components.
 
 Title: ${title}
@@ -189,7 +247,7 @@ Return ONLY valid JSON array:
 Rules:
 - Only include specific, named entities (not generic concepts like "database" or "testing")
 - Normalize names: "VM 202" not "vm202", "ClawMem" not "clawmem"
-- 0-10 entities. Return empty array [] if no specific entities found
+- 0-${cap} entities. Return empty array [] if no specific entities found
 - Include the most specific type for each entity
 - Do NOT extract the document's title as an entity
 - Do NOT extract heading labels, section names, or sentence fragments
@@ -217,7 +275,7 @@ Return ONLY the JSON array. /no_think`;
         ['person', 'project', 'service', 'tool', 'concept', 'org', 'location'].includes(e.type)
       )
       .filter(e => !isLowQualityEntity(e.name, e.type, title))
-      .slice(0, 10);
+      .slice(0, cap);
   } catch (err) {
     console.log(`[entity] LLM extraction failed:`, err);
     return [];
@@ -454,12 +512,14 @@ export async function enrichDocumentEntities(
 ): Promise<number> {
   try {
     // Get document content (snapshot for extraction)
+    // v0.8.3 (§1.5): fetch content_type so extractEntities can apply a
+    // content-type-aware cap instead of the flat slice(0, 10).
     const doc = db.prepare(`
-      SELECT d.title, c.doc as body
+      SELECT d.title, d.content_type, c.doc as body
       FROM documents d
       JOIN content c ON c.hash = d.hash
       WHERE d.id = ? AND d.active = 1
-    `).get(docId) as { title: string; body: string } | null;
+    `).get(docId) as { title: string; content_type: string | null; body: string } | null;
 
     if (!doc) {
       console.log(`[entity] Document ${docId} not found or inactive`);
@@ -478,8 +538,8 @@ export async function enrichDocumentEntities(
       return 0; // Same input, already enriched — skip
     }
 
-    // Step 1: Extract entities via LLM
-    const entities = await extractEntities(llm, doc.title, doc.body);
+    // Step 1: Extract entities via LLM (cap is content-type-aware as of v0.8.3 §1.5)
+    const entities = await extractEntities(llm, doc.title, doc.body, doc.content_type ?? undefined);
 
     // Recheck input hash before writing — abort if content changed during LLM call
     const recheckHash = db.prepare(`

package/src/store.ts

@@ -1543,6 +1543,10 @@ export function createStore(dbPath?: string, opts?: { readonly?: boolean; busyTi
 
     // Usage relation tracking — records relations between documents
     insertRelation: (fromDoc: number, toDoc: number, relType: string, weight: number = 1.0) => {
+      // v0.8.3 (§1.3): reject self-loops at the API boundary. A document
+      // relating to itself has no informational value for graph traversal
+      // and would pollute intent_search/find_similar neighborhoods.
+      if (fromDoc === toDoc) return;
       db.prepare(`
         INSERT INTO memory_relations (source_id, target_id, relation_type, weight, created_at)
         VALUES (?, ?, ?, ?, ?)
@@ -4224,6 +4228,10 @@ export async function syncBeadsIssues(
     const targetRow = db.prepare(`SELECT doc_id FROM beads_issues WHERE beads_id = ?`).get(dep.target_id) as { doc_id: number } | undefined;
 
     if (sourceRow && targetRow) {
+      // v0.8.3 (§1.3): mirror of insertRelation self-loop guard. Beads can
+      // theoretically express a self-dependency (e.g. a `relates-to` edge
+      // from an issue to itself); skip those before they land in the graph.
+      if (sourceRow.doc_id === targetRow.doc_id) continue;
       db.prepare(`
         INSERT OR IGNORE INTO memory_relations (source_id, target_id, relation_type, weight, metadata, created_at)
         VALUES (?, ?, ?, 1.0, ?, ?)