@geravant/sinain 1.13.0 → 1.14.0

package/.env.example

@@ -23,9 +23,11 @@ PRIVACY_MODE=standard              # off | standard | strict | paranoid
                                    # paranoid: almost nothing leaves your machine
 
 # ── Agent ────────────────────────────────────────────────────────────────────
-SINAIN_AGENT=claude                # claude | codex | junie | goose | aider | <custom command>
-                                   # MCP agents (claude, codex, junie, goose) call sinain tools directly
+SINAIN_AGENT=claude                # claude | openclaude | codex | junie | goose | aider | <custom command>
+                                   # MCP agents (claude, openclaude, codex, junie, goose) call sinain tools directly
                                    # Pipe agents (aider, custom) receive escalation text on stdin
+                                   # openclaude: set OPENAI_BASE_URL=http://localhost:11434/v1 + OPENAI_MODEL=<ollama-model>
+                                   #             to route through local Ollama. Run.sh auto-warms the model on startup.
 SINAIN_CORE_URL=http://localhost:9500
 SINAIN_POLL_INTERVAL=5             # seconds between escalation polls
 SINAIN_HEARTBEAT_INTERVAL=900      # seconds between heartbeat ticks (15 min)

package/config-shared.js

@@ -459,6 +459,7 @@ export async function stepAgent(existing, label = "Bare agent") {
     message: label,
     options: [
       { value: "claude", label: "Claude Code", hint: "Calls sinain tools directly — recommended" },
+      { value: "openclaude", label: "OpenClaude", hint: "Claude Code clone, local-first (Ollama/OpenAI-compat)" },
       { value: "codex", label: "Codex", hint: "Calls sinain tools directly" },
       { value: "goose", label: "Goose", hint: "Calls sinain tools directly" },
       { value: "junie", label: "Junie", hint: "JetBrains IDE agent" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geravant/sinain",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Ambient intelligence that sees what you see, hears what you hear, and acts on your behalf",
   "type": "module",
   "bin": {
@@ -25,6 +25,9 @@
     "index.ts",
     "openclaw.plugin.json",
     "sinain-memory",
+    "!sinain-memory/eval",
+    "!sinain-memory/tests",
+    "!sinain-memory/**/__pycache__",
     "sinain-knowledge",
     "sinain-core/src",
     "sinain-core/package.json",

package/sinain-agent/run.sh

@@ -55,7 +55,7 @@ fi
 JUNIE_HAS_MCP=false  # set during startup checks
 agent_has_mcp() {
   case "$AGENT" in
-    claude|codex|goose) return 0 ;;
+    claude|openclaude|codex|goose) return 0 ;;
     junie) $JUNIE_HAS_MCP ;;
     *) return 1 ;;
   esac
@@ -67,11 +67,11 @@ agent_has_mcp() {
 invoke_agent() {
   local prompt="$1"
   case "$AGENT" in
-    claude)
+    claude|openclaude)
       local turns="${2:-$AGENT_MAX_TURNS}"
       if [ -n "${SINAIN_SPAWN:-}" ]; then
         # Spawn: PreToolUse hook routes permission prompts to overlay HUD
-        claude \
+        "$AGENT" \
           --mcp-config "$MCP_CONFIG" \
           --settings "$SCRIPT_DIR/.claude/settings.json" \
           ${ALLOWED_TOOLS:+--allowedTools $ALLOWED_TOOLS} \
@@ -79,7 +79,7 @@ invoke_agent() {
           -p "$prompt"
       else
         # Escalation: auto-approve for speed (short-lived, read-heavy)
-        claude --enable-auto-mode \
+        "$AGENT" --enable-auto-mode \
           --mcp-config "$MCP_CONFIG" \
           ${ALLOWED_TOOLS:+--allowedTools $ALLOWED_TOOLS} \
           --max-turns "$turns" --output-format text \
@@ -227,6 +227,38 @@ print('  sinain extension added to ' + config_path)
   fi
 fi
 
+# Ollama warmup — pin the backing model so each agent invocation hits hot weights.
+# openclaude + Ollama via the OpenAI-compat endpoint does NOT forward keep_alive,
+# so we ping Ollama's native /api/generate once with keep_alive=-1 (persistent).
+# Applies to any agent pointed at an Ollama-compatible endpoint via OPENAI_BASE_URL.
+OLLAMA_WARMUP="${OLLAMA_WARMUP:-true}"
+if [ "$OLLAMA_WARMUP" = "true" ] && [ -n "${OPENAI_BASE_URL:-}" ]; then
+  if [[ "$OPENAI_BASE_URL" == *"11434"* ]] || [[ "$OPENAI_BASE_URL" == *"ollama"* ]]; then
+    # Derive Ollama host by stripping /v1 suffix from OPENAI_BASE_URL
+    OLLAMA_HOST="${OLLAMA_HOST:-${OPENAI_BASE_URL%/v1*}}"
+    OLLAMA_MODEL="${OLLAMA_MODEL:-${OPENAI_MODEL:-}}"
+    OLLAMA_KEEP_ALIVE="${OLLAMA_KEEP_ALIVE:--1}"  # -1 = persistent, or "24h", "30m", etc.
+    if [ -n "$OLLAMA_MODEL" ]; then
+      echo "Warming Ollama model $OLLAMA_MODEL at $OLLAMA_HOST (keep_alive=$OLLAMA_KEEP_ALIVE)..."
+      # Ollama accepts keep_alive as int (-1 = persistent) or duration string ("24h", "30m").
+      if [[ "$OLLAMA_KEEP_ALIVE" =~ ^-?[0-9]+$ ]]; then
+        WARMUP_PAYLOAD="{\"model\":\"$OLLAMA_MODEL\",\"prompt\":\"\",\"keep_alive\":$OLLAMA_KEEP_ALIVE,\"stream\":false}"
+      else
+        WARMUP_PAYLOAD="{\"model\":\"$OLLAMA_MODEL\",\"prompt\":\"\",\"keep_alive\":\"$OLLAMA_KEEP_ALIVE\",\"stream\":false}"
+      fi
+      if curl -sf -m 60 -X POST "$OLLAMA_HOST/api/generate" \
+          -H 'Content-Type: application/json' \
+          -d "$WARMUP_PAYLOAD" >/dev/null 2>&1; then
+        echo "  ✓ Model pinned in memory"
+      else
+        echo "  ⚠ Warmup failed — first request will cold-start the model"
+      fi
+    else
+      echo "  ⚠ OLLAMA_WARMUP=true but OPENAI_MODEL not set — skipping warmup"
+    fi
+  fi
+fi
+
 # Agent mode label
 if agent_has_mcp; then
   AGENT_MODE="MCP"

package/sinain-core/src/buffers/feed-buffer.ts

@@ -48,12 +48,14 @@ export class FeedBuffer {
     this.items.push(item);
     if (this.items.length > this._hwm) this._hwm = this.items.length;
 
-    // Fire onFull when buffer is at capacity AND enough new items have arrived
-    // since the last distillation (at least half the buffer replaced)
+    // Fire when enough new items have arrived since last distillation.
+    // 20 items ≈ 1.7 min of audio at ~12 items/min transcription rate.
+    // Distillation takes ~7s, so 20-item threshold gives 100s gap — safe margin.
+    // This means ~35 passes/hour, leaving <20 items undistilled at shutdown.
     const newSinceRearm = this._version - this._onFullVersion;
-    if (this.items.length >= this.maxSize
+    if (this.items.length >= 20
         && this._onFullCb && this._onFullArmed
-        && newSinceRearm >= Math.floor(this.maxSize / 2)) {
+        && newSinceRearm >= 20) {
       this._onFullArmed = false;
       const snapshot = [...this.items];
       queueMicrotask(() => this._onFullCb!(snapshot));

package/sinain-core/src/index.ts

@@ -67,35 +67,66 @@ async function queryKnowledgeFactsMulti(entities: string[], maxFacts: number): P
   ];
   const scriptPath = scriptCandidates.find(p => existsSync(p)) || scriptCandidates[0];
 
-  const results: string[] = [];
+  // Step 1: Get candidates from Python (RRF-ranked, no embedding — avoids deadlock)
+  // Request 2x candidates in JSON for re-ranking in Node.js
+  const candidateFacts: Array<Record<string, string>> = [];
   for (const dbPath of dbPaths) {
     if (!existsSync(dbPath)) continue;
     try {
-      const args = [scriptPath, "--db", dbPath, "--max-facts", String(maxFacts), "--format", "compact"];
+      const args = [scriptPath, "--db", dbPath, "--max-facts", String(maxFacts * 2), "--format", "json"];
       if (entities.length > 0) args.push("--entities", JSON.stringify(entities));
       const out = execFileSync("python3", args, { timeout: 5000, encoding: "utf-8" }).trim();
-      if (out) results.push(out);
+      if (out) {
+        const parsed = JSON.parse(out);
+        const facts = parsed.facts || parsed;
+        if (Array.isArray(facts)) candidateFacts.push(...facts);
+      }
     } catch { /* skip failed db */ }
   }
 
-  if (results.length === 0) return "";
-  if (results.length === 1) return results[0];
+  if (candidateFacts.length === 0) return "";
 
-  // Merge and deduplicate lines from both sources
-  const seen = new Set<string>();
-  const merged: string[] = [];
-  for (const block of results) {
-    for (const line of block.split("\n")) {
-      const key = line.replace(/\(confidence:.*$/, "").trim();
-      if (key && !seen.has(key)) {
-        seen.add(key);
-        merged.push(line);
-      }
+  // Step 2: Re-rank by embedding similarity in-process (no deadlock — model is in this process)
+  const queryText = entities.join(" ");
+  try {
+    if (embeddingService?.ready) {
+      const allTexts = [queryText, ...candidateFacts.map(f => f.value || "")];
+      const embeddings = await embeddingService.embed(allTexts);
+      const queryEmb = embeddings[0];
+      const scored = candidateFacts.map((f, i) => ({
+        fact: f,
+        sim: EmbeddingService.cosine(queryEmb, embeddings[i + 1]),
+      }));
+      scored.sort((a, b) => b.sim - a.sim);
+      candidateFacts.length = 0;
+      candidateFacts.push(...scored.slice(0, maxFacts).map(s => s.fact));
     }
+  } catch { /* embedding unavailable — use RRF order */ }
+
+  // Step 3: Format as compact text
+  const seen = new Set<string>();
+  const lines: string[] = [];
+  let total = 0;
+  const maxChars = 1200;
+  for (const f of candidateFacts.slice(0, maxFacts)) {
+    const eid = ((f as any).entity_id || (f as any).entityId || "").split(":").pop()?.slice(0, 20) || "?";
+    const value = (f as any).value || "";
+    const conf = (f as any).confidence || "?";
+    const count = (f as any).reinforce_count || "1";
+    const line = `${eid}: ${value} (${conf},${count}x)`;
+    const key = value.slice(0, 60);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    if (total + line.length + 2 > maxChars) break;
+    lines.push(line);
+    total += line.length + 2;
   }
-  return merged.slice(0, maxFacts).join("\n");
+  return lines.join("; ");
 }
 
+// Reference to embedding service — set during init
+let embeddingService: import("./embedding/service.js").EmbeddingService | null = null;
+
 /** List all entities from both local and workspace knowledge graphs. */
 async function listKnowledgeEntitiesMulti(max: number): Promise<string> {
   const { execFileSync } = await import("node:child_process");
@@ -340,7 +371,7 @@ async function main() {
     : null;
 
   // ── Initialize embedding service (non-blocking) ──
-  const embeddingService = new EmbeddingService();
+  embeddingService = new EmbeddingService();
   embeddingService.loadAsync(); // ~9s background load, server starts immediately
 
   // ── Initialize local knowledge pipeline ──
@@ -683,8 +714,8 @@ async function main() {
     },
     getSpawnPending: () => escalator.getSpawnPending(),
     respondSpawn: (id: string, result: string) => escalator.respondSpawn(id, result),
-    embedTexts: (texts: string[]) => embeddingService.embed(texts),
-    isEmbeddingReady: () => embeddingService.ready,
+    embedTexts: (texts: string[]) => embeddingService!.embed(texts),
+    isEmbeddingReady: () => embeddingService?.ready ?? false,
   });
 
   // ── Wire overlay profiling ──

package/sinain-memory/graph_query.py

@@ -330,6 +330,10 @@ def query_facts_hybrid(
             if eid and eid not in fact_map:
                 fact_map[eid] = f
 
+    # Return top RRF candidates. Embedding re-ranking is done by the caller
+    # (sinain-core Node.js) to avoid deadlock — the Python subprocess can't call
+    # back to sinain-core's /embed endpoint while sinain-core is blocked waiting
+    # for the subprocess.
     results = [fact_map[eid] for eid in sorted_ids[:max_facts] if eid in fact_map]
 
     # Expand top results with 1-hop graph neighbors
@@ -396,7 +400,7 @@ def format_facts_text(facts: list[dict], max_chars: int = 500) -> str:
     return "\n".join(lines)
 
 
-def format_facts_compact(facts: list[dict], max_chars: int = 400) -> str:
+def format_facts_compact(facts: list[dict], max_chars: int = 1200) -> str:
     """Encode facts for efficient escalation context injection.
 
     Compact format: domain/entity: value (conf, Nx)
@@ -409,7 +413,7 @@ def format_facts_compact(facts: list[dict], max_chars: int = 400) -> str:
     total = 0
     for f in facts:
         entity = f.get("entityId", "").split(":")[-1][:20]
-        value = f.get("value", "")[:60]
+        value = f.get("value", "")
         conf = f.get("confidence", "?")
         count = f.get("reinforce_count", "1")
         domain = f.get("domain", "")
@@ -469,7 +473,12 @@ def main() -> None:
         facts = query_top_facts(args.db, limit=args.top)
     elif args.entities:
         entities = json.loads(args.entities)
-        facts = query_facts_by_entities(args.db, entities, max_facts=args.max_facts)
+        # Use hybrid retrieval (FTS5 + tags + entity graph + RRF) for best results
+        query_text = " ".join(entities)
+        facts = query_facts_hybrid(args.db, query_text, max_facts=args.max_facts)
+        # Fallback to tag-only if hybrid returns nothing
+        if not facts:
+            facts = query_facts_by_entities(args.db, entities, max_facts=args.max_facts)
     else:
         facts = query_top_facts(args.db, limit=args.max_facts)
 

package/sinain-memory/knowledge_integrator.py

@@ -21,7 +21,9 @@ import json
 import re
 import shutil
 import sys
+import unicodedata
 from datetime import datetime, timezone
+from difflib import SequenceMatcher
 from pathlib import Path
 
 from common import (
@@ -121,9 +123,50 @@ def _fact_id(entity: str, attribute: str, value: str) -> str:
     return f"fact:{slug}-{h}"
 
 
+_UNICODE_PRE_MAP = str.maketrans({"ß": "ss", "ẞ": "SS"})
+
+
 def _normalize_entity(name: str) -> str:
-    """Normalize entity name to canonical form: lowercase, hyphenated, no punctuation."""
-    return re.sub(r"[^a-z0-9-]", "", name.lower().replace(" ", "-").replace("_", "-"))
+    """Normalize entity name to canonical form: lowercase, hyphenated, ASCII-transliterated."""
+    s = name.translate(_UNICODE_PRE_MAP)
+    s = unicodedata.normalize("NFKD", s)
+    s = s.encode("ascii", "ignore").decode("ascii")
+    s = s.lower().replace(" ", "-").replace("_", "-")
+    s = re.sub(r"[^a-z0-9-]", "", s)
+    s = re.sub(r"-{2,}", "-", s)
+    return s.strip("-")
+
+
+def _find_matching_entity(
+    name: str,
+    existing_names: dict[str, str],
+) -> str | None:
+    """Find an existing entity that fuzzy-matches `name`. Returns entity_node_id or None."""
+    if name in existing_names:
+        return existing_names[name]
+
+    # Hyphen-insensitive exact match (chatgpt == chat-gpt)
+    name_compact = name.replace("-", "")
+    for existing_name, node_id in existing_names.items():
+        if existing_name.replace("-", "") == name_compact:
+            return node_id
+
+    # Edit-distance fuzzy match
+    if len(name) < 3:
+        return None
+    threshold = 0.90
+    best_match = None
+    best_ratio = threshold
+    for existing_name, node_id in existing_names.items():
+        if len(existing_name) < 3:
+            continue
+        if frozenset({name, existing_name}) in _DEDUP_SKIP_PAIRS:
+            continue
+        ratio = SequenceMatcher(None, name, existing_name).ratio()
+        if ratio >= best_ratio:
+            best_ratio = ratio
+            best_match = node_id
+    return best_match
 
 
 def _canonicalize_ops(ops: list[dict], existing_entities: list[str], existing_facts: list[dict]) -> list[dict]:
@@ -528,7 +571,14 @@ def _execute_graph_ops(db_path: str, ops: list[dict], digest_ts: str, digest_ent
         # --- Build entity graph layer (two-layer model) ---
         if digest_entities and stats["asserted"] > 0:
             try:
-                # Create entity:* nodes from digest entities
+                # Load existing entity names for fuzzy matching
+                all_entity_nodes: dict[str, str] = {}  # {name: entity_node_id}
+                for r in store.entities_with_attr("name"):
+                    if r[0].startswith("entity:"):
+                        all_entity_nodes[r[1]] = r[0]
+
+                # Create entity:* nodes from digest entities (with fuzzy dedup)
+                entity_resolve: dict[str, str] = {}  # {normalized_name: resolved_node_id}
                 for ent in (digest_entities or []):
                     if isinstance(ent, dict):
                         ename = _normalize_entity(ent.get("name", ""))
@@ -539,12 +589,22 @@ def _execute_graph_ops(db_path: str, ops: list[dict], digest_ts: str, digest_ent
                     if not ename or len(ename) < 2:
                         continue
 
+                    # Check for fuzzy match against existing entities
+                    matched_id = _find_matching_entity(ename, all_entity_nodes)
+                    if matched_id:
+                        entity_resolve[ename] = matched_id
+                        if matched_id != f"entity:{ename}":
+                            print(f"  [graph] alias: \"{ename}\" → {matched_id}", file=sys.stderr)
+                        continue
+
                     entity_node_id = f"entity:{ename}"
                     existing = store.entity(entity_node_id)
                     if not existing:
                         tx = store.begin_tx("entity_graph")
                         store.assert_triple(tx, entity_node_id, "name", ename)
                         store.assert_triple(tx, entity_node_id, "type", etype)
+                    all_entity_nodes[ename] = entity_node_id
+                    entity_resolve[ename] = entity_node_id
 
                 # Link facts to their entity nodes via "about" ref edges
                 for op_data in ops:
@@ -554,18 +614,13 @@ def _execute_graph_ops(db_path: str, ops: list[dict], digest_ts: str, digest_ent
                     value = op_data.get("value", "")
                     attribute = op_data.get("attribute", "")
                     fact_eid = _fact_id(entity, attribute, value)
-                    entity_node_id = f"entity:{_normalize_entity(entity)}"
+                    norm_entity = _normalize_entity(entity)
+                    entity_node_id = entity_resolve.get(norm_entity, f"entity:{norm_entity}")
                     # Only link if entity node exists
                     if store.entity(entity_node_id):
                         tx = store.begin_tx("entity_graph")
                         store.assert_triple(tx, fact_eid, "about", entity_node_id, value_type="ref")
 
-                # Infer cross-entity refs from fact content
-                all_entity_nodes = {}
-                for r in store.entities_with_attr("name"):
-                    if r[0].startswith("entity:"):
-                        all_entity_nodes[r[1]] = r[0]  # {name: entity_id}
-
                 ref_count = 0
                 for fact_eid_row in store.entities_with_attr("value"):
                     fact_eid = fact_eid_row[0]
@@ -695,17 +750,146 @@ def _bootstrap_graph(memory_dir: str, db_path: str) -> dict:
     return {"bootstrapped": stats.get("asserted", 0)}
 
 
+# Pairs that fuzzy matching incorrectly clusters — reviewed and confirmed distinct.
+_DEDUP_SKIP_PAIRS = {
+    frozenset({"ai-driven-development", "spac-driven-development"}),
+    frozenset({"german", "germany"}),
+    frozenset({"llama", "ollama"}),
+    frozenset({"gemma", "gemma4"}),
+}
+
+
+def merge_entity_duplicates(db_path: str, dry_run: bool = True) -> dict:
+    """Merge fragmented entity nodes using fuzzy matching.
+
+    Idempotent: checks for migration:entity-dedup-v1 stamp.
+    """
+    from triplestore import TripleStore
+    store = TripleStore(db_path)
+
+    # Idempotency check
+    stamp = store.entity("migration:entity-dedup-v1")
+    if stamp:
+        print("migration:entity-dedup-v1 already applied — skipping", file=sys.stderr)
+        return {"status": "already_applied"}
+
+    # Load all entity nodes
+    all_entities: dict[str, str] = {}  # {name: entity_node_id}
+    for entity_id, name in store.entities_with_attr("name"):
+        if entity_id.startswith("entity:"):
+            all_entities[name] = entity_id
+
+    print(f"Total entity nodes: {len(all_entities)}", file=sys.stderr)
+
+    # Build clusters via greedy matching
+    remaining = dict(all_entities)  # copy
+    clusters: list[list[tuple[str, str]]] = []  # [[( name, node_id ), ...], ...]
+
+    while remaining:
+        seed_name, seed_id = next(iter(remaining.items()))
+        cluster = [(seed_name, seed_id)]
+        del remaining[seed_name]
+
+        # Find all matches for this seed
+        to_remove = []
+        for other_name, other_id in remaining.items():
+            matched = _find_matching_entity(other_name, {seed_name: seed_id})
+            if matched:
+                cluster.append((other_name, other_id))
+                to_remove.append(other_name)
+        for name in to_remove:
+            del remaining[name]
+
+        if len(cluster) > 1:
+            # Filter out known false-positive pairs
+            names_set = {n for n, _ in cluster}
+            if any(pair <= names_set for pair in _DEDUP_SKIP_PAIRS):
+                continue
+            clusters.append(cluster)
+
+    print(f"Found {len(clusters)} duplicate clusters", file=sys.stderr)
+
+    merge_count = 0
+    repoint_count = 0
+
+    for cluster in clusters:
+        # Canonical selection: if any entity has significantly more backrefs (5+),
+        # use it. Otherwise prefer longest name (most complete spelling).
+        max_refs = max(len(store.backrefs(nid)) for _, nid in cluster)
+        if max_refs >= 5:
+            cluster.sort(key=lambda x: (-len(store.backrefs(x[1])), -len(x[0]), x[0]))
+        else:
+            cluster.sort(key=lambda x: (-len(x[0]), x[0]))
+        canonical_name, canonical_id = cluster[0]
+        duplicates = cluster[1:]
+
+        dup_names = [d[0] for d in duplicates]
+        print(f"  cluster: {canonical_name} ← {dup_names}", file=sys.stderr)
+
+        if dry_run:
+            merge_count += len(duplicates)
+            continue
+
+        for dup_name, dup_id in duplicates:
+            # Re-point all refs pointing to this duplicate
+            refs = store.backrefs(dup_id)
+            for src_entity, attr in refs:
+                tx = store.begin_tx("entity_dedup")
+                store.retract_triple(tx, src_entity, attr, dup_id)
+                store.assert_triple(tx, src_entity, attr, canonical_id, value_type="ref")
+                repoint_count += 1
+
+            # Retract all triples of the duplicate entity itself
+            dup_attrs = store.entity(dup_id)
+            tx = store.begin_tx("entity_dedup")
+            for attr, values in dup_attrs.items():
+                if not isinstance(values, list):
+                    values = [values]
+                for val in values:
+                    store.retract_triple(tx, dup_id, attr, str(val))
+
+            merge_count += 1
+
+    # Stamp migration
+    if not dry_run and clusters:
+        tx = store.begin_tx("entity_dedup")
+        store.assert_triple(tx, "migration:entity-dedup-v1", "applied_at",
+                            datetime.now(timezone.utc).isoformat())
+        store.assert_triple(tx, "migration:entity-dedup-v1", "clusters_merged",
+                            str(len(clusters)))
+
+    result = {
+        "status": "dry_run" if dry_run else "applied",
+        "clusters": len(clusters),
+        "entities_merged": merge_count,
+        "refs_repointed": repoint_count,
+    }
+    print(json.dumps(result, indent=2), file=sys.stderr)
+    return result
+
+
 def main() -> None:
     parser = argparse.ArgumentParser(description="Knowledge Integrator")
     parser.add_argument("--memory-dir", required=True, help="Path to memory/ directory")
     parser.add_argument("--digest", default=None, help="SessionDigest JSON string")
     parser.add_argument("--bootstrap", action="store_true", help="One-time: seed graph from playbook")
     parser.add_argument("--retag", action="store_true", help="Re-extract tags for all existing facts")
+    parser.add_argument("--dedup-entities", action="store_true", help="Merge fragmented entity nodes")
+    parser.add_argument("--dry-run", action="store_true", help="Preview changes without applying")
     args = parser.parse_args()
 
     memory_dir = args.memory_dir
     db_path = str(Path(memory_dir) / "knowledge-graph.db")
 
+    # Entity dedup mode: merge fragmented entity nodes
+    if args.dedup_entities:
+        if not Path(db_path).exists():
+            output_json({"error": "knowledge-graph.db not found"})
+            return
+        result = merge_entity_duplicates(db_path, dry_run=args.dry_run)
+        output_json(result)
+        return
+
     # Bootstrap mode: seed graph from current playbook
     if args.bootstrap:
         result = _bootstrap_graph(memory_dir, db_path)