clawmem 0.2.0 → 0.2.1

package/AGENTS.md

@@ -634,9 +634,20 @@ Symptom: embed --force with new model produces 3 docs stuck as "Unembedded" but
   → Fix: Delete partial content_vectors + vectors_vec for the stuck hashes, then re-run embed (no --force).
     The vec0 DELETE try-catch prevents cascading failures during the re-embed.
 
+Symptom: reindex --force after v0.2.0 upgrade shows no entity extraction
+  → `reindex --force` treats existing docs as updates (isNew=false). The A-MEM pipeline
+    skips entity extraction, link generation, and evolution for updates to avoid churn.
+  → Fix: Use `clawmem reindex --enrich` instead. The `--enrich` flag forces the full
+    enrichment pipeline (entity extraction + links + evolution) on all documents.
+  → `--force` alone only refreshes A-MEM notes (keywords, tags, context). `--enrich`
+    is needed after major upgrades that add new enrichment stages.
+
 Symptom: CLI reindex/update falls back to node-llama-cpp Vulkan (not GPU server)
   → GPU env vars only in systemd drop-in, not in wrapper script. CLI invocations missed them.
   → Fixed 2026-02-12: bin/clawmem wrapper exports CLAWMEM_EMBED_URL/LLM_URL/RERANK_URL defaults.
+  → Always run ClawMem via the `bin/clawmem` wrapper, not `bun run src/clawmem.ts` directly.
+    The wrapper sets CLAWMEM_EMBED_URL/LLM_URL/RERANK_URL defaults. Scripts or inline bun
+    commands that bypass the wrapper will fall back to in-process node-llama-cpp (slow, CPU).
 
 Symptom: "UserPromptSubmit hook error" on context-surfacing hook (intermittent)
   → SQLite contention between the watcher and the hook. The watcher processes filesystem events

package/CLAUDE.md

@@ -634,9 +634,20 @@ Symptom: embed --force with new model produces 3 docs stuck as "Unembedded" but
   → Fix: Delete partial content_vectors + vectors_vec for the stuck hashes, then re-run embed (no --force).
     The vec0 DELETE try-catch prevents cascading failures during the re-embed.
 
+Symptom: reindex --force after v0.2.0 upgrade shows no entity extraction
+  → `reindex --force` treats existing docs as updates (isNew=false). The A-MEM pipeline
+    skips entity extraction, link generation, and evolution for updates to avoid churn.
+  → Fix: Use `clawmem reindex --enrich` instead. The `--enrich` flag forces the full
+    enrichment pipeline (entity extraction + links + evolution) on all documents.
+  → `--force` alone only refreshes A-MEM notes (keywords, tags, context). `--enrich`
+    is needed after major upgrades that add new enrichment stages.
+
 Symptom: CLI reindex/update falls back to node-llama-cpp Vulkan (not GPU server)
   → GPU env vars only in systemd drop-in, not in wrapper script. CLI invocations missed them.
   → Fixed 2026-02-12: bin/clawmem wrapper exports CLAWMEM_EMBED_URL/LLM_URL/RERANK_URL defaults.
+  → Always run ClawMem via the `bin/clawmem` wrapper, not `bun run src/clawmem.ts` directly.
+    The wrapper sets CLAWMEM_EMBED_URL/LLM_URL/RERANK_URL defaults. Scripts or inline bun
+    commands that bypass the wrapper will fall back to in-process node-llama-cpp (slow, CPU).
 
 Symptom: "UserPromptSubmit hook error" on context-surfacing hook (intermittent)
   → SQLite contention between the watcher and the hook. The watcher processes filesystem events

package/README.md

@@ -149,6 +149,25 @@ clawmem update --embed
 clawmem doctor
 ```
 
+### Upgrading
+
+```bash
+bun update -g clawmem   # or: npm update -g clawmem
+```
+
+Database schema migrates automatically on next startup (new tables and columns are added via `CREATE IF NOT EXISTS` / `ALTER TABLE ADD COLUMN`).
+
+After **major version updates** (e.g. 0.1.x → 0.2.0) that add new enrichment pipelines, run a full enrichment pass to backfill existing documents:
+
+```bash
+clawmem reindex --enrich  # Full enrichment: entity extraction + links + evolution for all docs
+clawmem embed             # Re-embed if upgrading embedding models (not needed for most updates)
+```
+
+`--enrich` forces the complete A-MEM pipeline (entity extraction, link generation, memory evolution) on all documents, not just new ones. Without it, reindex only refreshes metadata for existing docs.
+
+Routine patch updates (e.g. 0.2.0 → 0.2.1) do not require reindexing.
+
 ### Integration
 
 #### Claude Code

package/SKILL.md

@@ -272,7 +272,7 @@ Once escalated, route by query type:
 | `beads_sync` | Sync Beads issues from Dolt backend into memory. |
 | `index_stats` | Doc counts, embedding coverage, content type distribution. |
 | `status` | Quick index health. |
-| `reindex` | Force re-index (BM25 only, does NOT embed). |
+| `reindex` | Force re-index (BM25 only, does NOT embed). Use `--enrich` after major upgrades to backfill entity extraction + links on existing docs. |
 | `memory_evolution_status` | Track how a doc's A-MEM metadata evolved over time. |
 | `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. |
@@ -660,6 +660,14 @@ echo "user query" | clawmem surface --context --stdin
 echo "session-id" | clawmem surface --bootstrap --stdin
 ```
 
+### Enrichment Commands
+
+```bash
+clawmem reindex --enrich        # Full A-MEM pipeline on ALL docs (entity extraction,
+                                # link generation, memory evolution). Use after major upgrades.
+                                # Without --enrich, reindex only refreshes metadata for changed docs.
+```
+
 ### Analysis Commands
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmem",
-  "version": "0.2.0",
+  "version": "0.2.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

@@ -1269,6 +1269,7 @@ async function cmdWatch() {
 
 async function cmdReindex(args: string[]) {
   const force = args.includes("--force") || args.includes("-f");
+  const enrich = args.includes("--enrich");
   const collections = collectionsList();
 
   if (collections.length === 0) {
@@ -1283,9 +1284,13 @@ async function cmdReindex(args: string[]) {
     console.log(`${c.yellow}Force reindex: deactivated all documents${c.reset}`);
   }
 
+  if (enrich) {
+    console.log(`${c.cyan}Full enrichment: entity extraction + links + evolution for all documents${c.reset}`);
+  }
+
   for (const col of collections) {
     console.log(`Indexing ${c.bold}${col.name}${c.reset} (${col.path})...`);
-    const stats = await indexCollection(s, col.name, col.path, col.pattern);
+    const stats = await indexCollection(s, col.name, col.path, col.pattern, { forceEnrich: enrich });
     console.log(`  +${stats.added} added, ~${stats.updated} updated, =${stats.unchanged} unchanged, -${stats.removed} removed`);
   }
 }
@@ -2202,7 +2207,7 @@ ${c.bold}Setup:${c.reset}
 ${c.bold}Indexing:${c.reset}
   clawmem update [--pull] [--embed]    Re-scan collections (--embed auto-embeds)
   clawmem embed [-f]                   Generate fragment embeddings
-  clawmem reindex [--force]            Full re-index
+  clawmem reindex [--force] [--enrich]  Full re-index (--enrich: run entity extraction + links on all docs)
   clawmem watch                        File watcher daemon
   clawmem status                       Show index status
 

package/src/indexer.ts

@@ -166,7 +166,8 @@ export async function indexCollection(
   store: Store,
   collectionName: string,
   collectionPath: string,
-  pattern: string = "**/*.md"
+  pattern: string = "**/*.md",
+  options?: { forceEnrich?: boolean }
 ): Promise<IndexStats> {
   const stats: IndexStats = { added: 0, updated: 0, unchanged: 0, removed: 0 };
   const activePaths = new Set<string>();
@@ -223,6 +224,10 @@ export async function indexCollection(
 
         if (existingRow?.content_hash === contentHash) {
           stats.unchanged++;
+          if (options?.forceEnrich) {
+            // --enrich: queue unchanged docs for full enrichment (entity extraction, links)
+            enrichQueue.push({ docId: existing.id, isNew: true });
+          }
           continue;
         }
 
@@ -319,8 +324,9 @@ export async function indexCollection(
   }
 
   // A-MEM enrichment runs after successful commit (LLM calls should not block transaction)
+  // forceEnrich overrides isNew to true — triggers full pipeline (entity extraction, links, evolution)
   for (const { docId, isNew } of enrichQueue) {
-    await store.postIndexEnrich(llm, docId, isNew);
+    await store.postIndexEnrich(llm, docId, options?.forceEnrich ? true : isNew);
   }
 
   return stats;