@psiclawops/hypermem 0.9.7 → 0.9.9

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to hypermem are documented here.
 
+## 0.9.9 - 2026-05-09
+
+- **Replay duplication cleanup is operator-visible.** `hypermem-cleanup` now ships as a package CLI, dry-runs by default, reports timestamp-stamped Gateway replay duplicate debt without printing message content, and applies repairs only with `--apply` after creating a SQLite backup, rewiring local message references, rebuilding FTS, and passing integrity checks.
+- **Doctor warns on stamped replay duplicate debt.** `hypermem-doctor` now scans the HyperMem data dir for timestamp-stamped user replay duplicate rows and emits a hard-to-miss `stamped-replay-duplicate-debt` warning with the cleanup dry-run command.
+- **Operational memory defaults tightened.** Shipped defaults now favor stable pressure over maximum recall: lower first-turn warm history load, bounded facts/keystones, 250 hot history messages, and cross-session context off by default while LoCoMo tuning continues.
+- **Boundary user turns are persisted reliably.** The context-engine plugin now recovers the current plain user message at the afterTurn boundary when OpenClaw pre-prompt counts already include it, preventing assistant-only replay gaps in HyperMem's SQLite history.
+- **Plugin audit gate is clean.** Context-engine and memory-plugin packages pin the transitive `fast-xml-builder` audit fix through package overrides and refreshed lockfiles.
+
+## 0.9.8 - 2026-05-03
+
+- **Deterministic runtime validation added.** `hypermem-validate-runtime` now ships with the package and installer payload, seeds an isolated validation fixture, and verifies message writes, FTS, structured facts, vector indexing/search when enabled, warm, and compose without an answer LLM. Install docs now treat runtime validation as part of completion.
+- **Long-horizon recall widened for EasyLoCoMo.** Steady semantic recall now uses a larger memory envelope and candidate pool, closer to the published Mem0 token-efficient LoCoMo posture instead of starving single-hop and temporal evidence.
+- **Temporal recall is query-shaped.** Temporal retrieval now over-fetches indexed facts, scores them against query terms, and injects relevant temporal evidence rather than blindly taking the latest rows. This targets wrong-date failures on `when did X` questions.
+- **Old episodic evidence is preserved for benchmark-style questions.** Long-horizon QA disables production recency decay and relaxes FTS-only episode floors so valid historical evidence is not filtered out solely because it is old.
+- **Long-horizon fusion weights now favor exact evidence.** Benchmark-style questions use a lower RRF k, modest FTS weight boost, and wider reranker candidate window so names, dates, and quoted objects can outrank semantically-near but wrong old chatter without changing normal production turns.
+
 ## 0.9.7 - 2026-05-02
 
 - **OpenClaw Plugin SDK imports modernized.** HyperCompositor and HyperMem memory now import plugin entry helpers through the canonical public Plugin SDK surface and refresh OpenClaw/Plugin SDK build provenance to the validated runtime.

package/INSTALL.md

@@ -79,8 +79,9 @@ Release validation details live in [docs/INTEGRATION_VALIDATION.md](./docs/INTEG
 `hypermem-install` creates the current recommended starter config automatically when `~/.openclaw/hypermem/config.json` is missing. The shipped starter config is installation-safe FTS5 mode:
 
 - `embedding.provider: "none"`
-- `warmHistoryBudgetFraction: 0.45`
-- standard fact, keystone, and history caps
+- `warmHistoryBudgetFraction: 0.27`
+- bounded fact, keystone, and history caps
+- cross-session context disabled by default
 
 This is intentional. A clean first install should load, compose, and verify without requiring Ollama or an external API key. The result is **YELLOW** install readiness: HyperMem is active with keyword recall, but semantic vector recall is disabled. Upgrade to Ollama, OpenRouter, or Gemini after the baseline install is active.
 
@@ -152,15 +153,34 @@ OpenClaw loads the plugin runtime from `~/.openclaw/plugins/hypermem/`.
 
 ### Verification checkpoints
 
-Run the installed-system doctor first:
+Run the installed-system doctor and deterministic runtime validator first:
 
 ```bash
 hypermem-doctor --fix-plan
+hypermem-cleanup --data-dir ~/.openclaw/hypermem
+hypermem-validate-runtime --allow-no-embedding
 ```
 
 `hypermem-doctor` is read-only. It inspects OpenClaw config, HyperMem config, plugin wiring, recommended OpenClaw runtime settings, data directory shape, runtime plugin load state, and active model context-window risk. It prints exact `openclaw config set ...` commands when something needs review. It does not edit config or restart the gateway.
 
-Expected result after a complete install: no required failures. Recommendation warnings should be reviewed before production use, especially context-window warnings for GPT/OpenAI-compatible/local gateways.
+`hypermem-validate-runtime` writes a tiny isolated validation agent, then checks message persistence, FTS, structured facts, vector indexing/search when embeddings are enabled, warm, and compose. It does not call an answer LLM. Expected result after a complete install: doctor has no required failures and runtime validation reports `consistencyScore: 1`. Recommendation warnings should be reviewed before production use, especially context-window warnings for GPT/OpenAI-compatible/local gateways.
+
+### Replay duplicate cleanup after upgrade
+
+If agents report repeated user messages after a restart, run the read-only cleanup scan. This is now part of the obvious post-upgrade diagnostic path, not tribal knowledge:
+
+```bash
+hypermem-doctor --fix-plan
+hypermem-cleanup --data-dir ~/.openclaw/hypermem
+```
+
+Only apply during a maintenance window after Gateway/OpenClaw writers are stopped:
+
+```bash
+hypermem-cleanup --data-dir ~/.openclaw/hypermem --apply
+```
+
+Apply mode writes a SQLite backup, rewrites local references, rebuilds FTS, and rolls back unless integrity and foreign-key checks pass.
 
 Walk the install state machine explicitly if you need a manual check:
 
@@ -849,12 +869,12 @@ Key starter defaults:
     "budgetFraction": 0.6,
     "contextWindowReserve": 0.25,
     "targetBudgetFraction": 0.50,
-    "warmHistoryBudgetFraction": 0.45,
-    "maxFacts": 28,
+    "warmHistoryBudgetFraction": 0.27,
+    "maxFacts": 25,
     "maxHistoryMessages": 250,
     "maxCrossSessionContext": 0,
-    "keystoneHistoryFraction": 0.20,
-    "keystoneMaxMessages": 15,
+    "keystoneHistoryFraction": 0.15,
+    "keystoneMaxMessages": 12,
     "hyperformProfile": "standard"
   }
 }
@@ -929,7 +949,7 @@ Use it during install and after model changes. `--strict` exits non-zero if a mo
 ```json
 {
   "compositor": {
-    "budgetFraction": 0.55,
+    "budgetFraction": 0.6,
     "contextWindowReserve": 0.25,
     "warmHistoryBudgetFraction": 0.27,
     "contextWindowOverrides": {

package/README.md

@@ -455,11 +455,15 @@ openclaw config set plugins.allow '["existing-plugin","hypercompositor","hyperme
 
 openclaw gateway restart
 hypermem-doctor --fix-plan
+hypermem-cleanup --data-dir ~/.openclaw/hypermem
 hypermem-status --health
+hypermem-validate-runtime --allow-no-embedding
 hypermem-model-audit --strict
 ```
 
-`hypermem-doctor` is the confidence check: it validates plugin wiring, plugin registry refresh readiness, runtime load state, recommended OpenClaw settings such as `contextPruning.mode=off`, GPT-5 personality overlay off, startup/bootstrap injection sizing, compaction safety settings including `maxActiveTranscriptBytes` remaining unset for HyperMem-managed compaction, HyperMem data files, and model context-window overrides for GPT/OpenAI-compatible/local gateways. It is read-only and prints a reviewable fix plan.
+`hypermem-cleanup` is the operator-safe repair tool for timestamp-stamped Gateway replay duplicate rows. It is dry-run by default, prints no message content, creates backups in apply mode, rewrites local message references, rebuilds FTS, and commits only after SQLite integrity checks pass. `hypermem-doctor` warns with `stamped-replay-duplicate-debt` when cleanup should be considered.
+
+`hypermem-doctor` is the configuration confidence check: it validates plugin wiring, plugin registry refresh readiness, runtime load state, recommended OpenClaw settings such as `contextPruning.mode=off`, GPT-5 personality overlay off, startup/bootstrap injection sizing, compaction safety settings including `maxActiveTranscriptBytes` remaining unset for HyperMem-managed compaction, HyperMem data files, and model context-window overrides for GPT/OpenAI-compatible/local gateways. It is read-only and prints a reviewable fix plan. `hypermem-validate-runtime` is the deterministic component check: it seeds a tiny isolated fixture and verifies write, FTS, facts, vector indexing/search when enabled, warm, and compose without using an answer LLM.
 
 Full install, upgrade, source-clone, embedding provider, reranker, fleet config, and rollback guidance lives in **[INSTALL.md](./INSTALL.md)**.
 

package/assets/default-config.json

@@ -23,13 +23,28 @@
     "budgetFraction": 0.6,
     "contextWindowReserve": 0.25,
     "targetBudgetFraction": 0.5,
-    "warmHistoryBudgetFraction": 0.45,
-    "maxFacts": 28,
+    "warmHistoryBudgetFraction": 0.27,
+    "maxFacts": 25,
     "maxHistoryMessages": 250,
     "maxCrossSessionContext": 0,
-    "keystoneHistoryFraction": 0.2,
-    "keystoneMaxMessages": 15,
-    "hyperformProfile": "standard"
+    "keystoneHistoryFraction": 0.15,
+    "keystoneMaxMessages": 12,
+    "hyperformProfile": "standard",
+    "entityBridge": {
+      "enabled": false,
+      "structuredHandoff": false,
+      "pprEnabled": false,
+      "liveIndexingEnabled": false,
+      "maxTokens": 1200,
+      "maxGraphEdges": 5000,
+      "maxGraphNodes": 2000,
+      "maxCandidateMessagesBeforeRanking": 500,
+      "maxSeedEntities": 4,
+      "maxSeedFacets": 4,
+      "pprMaxIterations": 20,
+      "pprTeleportProbability": 0.15,
+      "pprConvergenceTolerance": 1e-06
+    }
   },
   "indexer": {
     "enabled": true,

package/assets/runtime-validation-fixture.json

@@ -0,0 +1,123 @@
+{
+  "schemaVersion": 1,
+  "name": "hypermem-runtime-validation",
+  "description": "Small deterministic fixture for installed HyperMem runtime validation. It validates message storage, FTS, library facts, vector indexing/search, warm, compose, current-value recall, temporal details, and negative-control recall without an answer LLM.",
+  "agentPrefix": "hypermem-runtime-validation",
+  "messages": [
+    {
+      "sessionId": "session-1",
+      "date": "2026-01-10T09:00:00Z",
+      "role": "user",
+      "content": "[runtime-fixture alpha] Riley stores the launch checklist in a teal binder in the north lab."
+    },
+    {
+      "sessionId": "session-1",
+      "date": "2026-01-10T09:01:00Z",
+      "role": "assistant",
+      "content": "Recorded: teal binder, north lab, launch checklist."
+    },
+    {
+      "sessionId": "session-1",
+      "date": "2026-01-10T09:02:00Z",
+      "role": "user",
+      "content": "[runtime-fixture beta] The backup generator codename is Copper Fox and it runs on Tuesdays."
+    },
+    {
+      "sessionId": "session-2",
+      "date": "2026-02-14T15:30:00Z",
+      "role": "user",
+      "content": "[runtime-fixture gamma] The old incident channel was #ops-red, but it was replaced by #ops-green on February 14."
+    },
+    {
+      "sessionId": "session-2",
+      "date": "2026-02-14T15:31:00Z",
+      "role": "assistant",
+      "content": "Current incident channel should be #ops-green; #ops-red is old."
+    },
+    {
+      "sessionId": "session-2",
+      "date": "2026-02-14T15:32:00Z",
+      "role": "user",
+      "content": "[runtime-fixture delta] Mira's pager handoff window is 18:00 to 20:00 Arizona time."
+    },
+    {
+      "sessionId": "session-3",
+      "date": "2026-03-22T11:45:00Z",
+      "role": "user",
+      "content": "[runtime-fixture epsilon] The release mascot is a brass otter carrying a small lantern."
+    },
+    {
+      "sessionId": "session-3",
+      "date": "2026-03-22T11:46:00Z",
+      "role": "assistant",
+      "content": "Noted release mascot: brass otter with lantern."
+    },
+    {
+      "sessionId": "session-3",
+      "date": "2026-03-22T11:47:00Z",
+      "role": "user",
+      "content": "[runtime-fixture zeta] There is no record of a purple submarine in this validation fixture."
+    }
+  ],
+  "facts": [
+    {
+      "domain": "runtime-validation",
+      "content": "Runtime validation structured fact: the backup generator codename is Copper Fox and it runs on Tuesdays."
+    },
+    {
+      "domain": "runtime-validation",
+      "content": "Runtime validation structured fact: the current incident channel is #ops-green; #ops-red is obsolete."
+    },
+    {
+      "domain": "runtime-validation",
+      "content": "Runtime validation structured fact: Mira's pager handoff window is 18:00 to 20:00 Arizona time."
+    }
+  ],
+  "probes": [
+    {
+      "id": "message-fts-exact-anchor",
+      "component": "message-fts",
+      "query": "teal binder north lab launch checklist",
+      "required": ["teal binder", "north lab", "launch checklist"]
+    },
+    {
+      "id": "message-fts-late-session",
+      "component": "message-fts",
+      "query": "brass otter lantern",
+      "required": ["brass otter", "lantern"]
+    },
+    {
+      "id": "semantic-structured-fact",
+      "component": "semantic",
+      "query": "standby power system codename weekly schedule",
+      "required": ["Copper Fox", "Tuesdays"]
+    },
+    {
+      "id": "semantic-current-value",
+      "component": "semantic",
+      "query": "current incident channel replacement",
+      "required": ["#ops-green"]
+    },
+    {
+      "id": "compose-temporal-detail",
+      "component": "compose",
+      "sessionId": "session-2",
+      "query": "When is Mira's pager handoff window?",
+      "required": ["18:00", "20:00", "Arizona"]
+    },
+    {
+      "id": "compose-late-session-detail",
+      "component": "compose",
+      "sessionId": "session-3",
+      "query": "What is the release mascot?",
+      "required": ["brass otter", "lantern"]
+    },
+    {
+      "id": "compose-negative-control",
+      "component": "compose",
+      "sessionId": "session-3",
+      "query": "What does the fixture say about a purple submarine?",
+      "required": ["no record", "purple submarine"]
+    }
+  ]
+}

package/bin/hypermem-cleanup.mjs

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+/**
+ * hypermem-cleanup — operator-safe repair utilities for persisted HyperMem DBs.
+ *
+ * Default command repairs timestamp-stamped replay duplicates caused by Gateway
+ * transcript restore re-recording the same user turn. It is read-only unless
+ * --apply is passed, and apply mode writes a SQLite backup first by default.
+ */
+
+import { existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { exit } from 'node:process';
+import { DatabaseSync } from 'node:sqlite';
+
+const STAMPED_PREFIX_RE = /^\[[A-Z][a-z]{2} \d{4}-\d{2}-\d{2} \d{2}:\d{2} [A-Z]{2,4}\]/;
+const DEFAULT_DATA_DIR = join(process.env.HOME || '', '.openclaw', 'hypermem');
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) {
+      out._.push(arg);
+      continue;
+    }
+    const key = arg.slice(2);
+    const next = argv[i + 1];
+    if (next == null || next.startsWith('--')) out[key] = true;
+    else {
+      out[key] = next;
+      i++;
+    }
+  }
+  return out;
+}
+
+function usage() {
+  console.log(`Usage: hypermem-cleanup [options]
+
+Repairs known persisted-data issues. Default mode is a dry-run scan for
+Gateway timestamp-stamped user replay duplicates.
+
+Options:
+  --data-dir <path>        HyperMem data dir (default: ~/.openclaw/hypermem)
+  --db <path>              Scan one messages.db instead of all agents
+  --agent <id>             Restrict --data-dir scan to one agent
+  --apply                  Delete duplicate rows and repair references
+  --backup-dir <path>      Backup directory for apply mode (default: beside DB)
+  --no-backup              Disable apply-mode backup (not recommended)
+  --json                   Print machine-readable JSON
+  --examples <n>           Include up to n hashed examples per DB (default: 5)
+  --help                   Show this help
+
+Safety:
+  - dry-run is default
+  - content is not printed; examples use SHA-256 prefixes and counts
+  - apply mode keeps the earliest row per exact duplicate group
+  - apply mode rewrites local message references, rebuilds FTS, and runs
+    integrity checks before committing
+`);
+}
+
+function isoStamp() {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+function sqlLiteral(value) {
+  return `'${String(value).replaceAll("'", "''")}'`;
+}
+
+function tableExists(db, table) {
+  const row = db.prepare("SELECT 1 AS ok FROM sqlite_master WHERE type IN ('table','view') AND name = ?").get(table);
+  return Boolean(row);
+}
+
+function columnExists(db, table, column) {
+  if (!tableExists(db, table)) return false;
+  return db.prepare(`PRAGMA table_info(${table})`).all().some((row) => row.name === column);
+}
+
+function firstTableColumns(db, table) {
+  if (!tableExists(db, table)) return [];
+  return db.prepare(`PRAGMA table_info(${table})`).all().map((row) => row.name);
+}
+
+function sha12(text) {
+  return createHash('sha256').update(text).digest('hex').slice(0, 12);
+}
+
+function resolveDbTargets({ dataDir, dbPath, agent }) {
+  if (dbPath) {
+    const resolved = resolve(dbPath);
+    if (!existsSync(resolved)) throw new Error(`messages.db not found: ${resolved}`);
+    return [{ agent: agent || dirname(resolved).split('/').pop() || 'unknown', dbPath: resolved }];
+  }
+  const agentsDir = join(resolve(dataDir || DEFAULT_DATA_DIR), 'agents');
+  if (!existsSync(agentsDir)) throw new Error(`HyperMem agents dir not found: ${agentsDir}`);
+  const agents = agent ? [agent] : readdirSync(agentsDir).sort();
+  const targets = [];
+  for (const id of agents) {
+    const candidate = join(agentsDir, id, 'messages.db');
+    if (existsSync(candidate)) targets.push({ agent: id, dbPath: candidate });
+  }
+  if (targets.length === 0) throw new Error(`No messages.db targets found under ${agentsDir}`);
+  return targets;
+}
+
+function readRows(db) {
+  const cols = firstTableColumns(db, 'messages');
+  if (!cols.includes('text_content') || !cols.includes('conversation_id') || !cols.includes('role')) {
+    throw new Error('messages table does not have the expected HyperMem columns');
+  }
+  const hasConversations = tableExists(db, 'conversations');
+  const sql = hasConversations
+    ? `SELECT m.id, m.conversation_id, c.session_key, m.agent_id, m.role, m.text_content,
+              COALESCE(m.tool_calls, '') AS tool_calls,
+              COALESCE(m.tool_results, '') AS tool_results,
+              COALESCE(m.message_index, 0) AS message_index,
+              m.created_at
+         FROM messages m
+         LEFT JOIN conversations c ON c.id = m.conversation_id
+        WHERE m.role = 'user' AND m.text_content IS NOT NULL`
+    : `SELECT id, conversation_id, NULL AS session_key, agent_id, role, text_content,
+              COALESCE(tool_calls, '') AS tool_calls,
+              COALESCE(tool_results, '') AS tool_results,
+              COALESCE(message_index, 0) AS message_index,
+              created_at
+         FROM messages
+        WHERE role = 'user' AND text_content IS NOT NULL`;
+  return db.prepare(sql).all();
+}
+
+function findStampedUserDuplicateGroups(db) {
+  const groups = new Map();
+  for (const row of readRows(db)) {
+    const text = String(row.text_content || '');
+    if (!STAMPED_PREFIX_RE.test(text.trimStart())) continue;
+    const key = [row.conversation_id, row.role, text, row.tool_calls || '', row.tool_results || ''].join('\u0000');
+    const list = groups.get(key) || [];
+    list.push(row);
+    groups.set(key, list);
+  }
+
+  const duplicateGroups = [];
+  for (const rows of groups.values()) {
+    if (rows.length < 2) continue;
+    rows.sort((a, b) => {
+      const ai = Number(a.message_index || 0);
+      const bi = Number(b.message_index || 0);
+      if (ai !== bi) return ai - bi;
+      return Number(a.id) - Number(b.id);
+    });
+    const keep = rows[0];
+    duplicateGroups.push({ keep, duplicates: rows.slice(1), all: rows });
+  }
+  duplicateGroups.sort((a, b) => String(a.keep.created_at || '').localeCompare(String(b.keep.created_at || '')) || Number(a.keep.id) - Number(b.keep.id));
+  return duplicateGroups;
+}
+
+function summarizeTarget(target, groups, exampleLimit) {
+  const duplicateRows = groups.reduce((sum, g) => sum + g.duplicates.length, 0);
+  const conversations = new Set(groups.map((g) => g.keep.conversation_id));
+  const first = groups[0]?.keep?.created_at || null;
+  const lastGroup = groups[groups.length - 1];
+  const lastRows = lastGroup ? lastGroup.all : [];
+  const last = lastRows.length ? lastRows.map((r) => r.created_at).sort().at(-1) : null;
+  const examples = groups.slice(0, exampleLimit).map((g) => ({
+    conversationId: g.keep.conversation_id,
+    sessionKey: g.keep.session_key || null,
+    keepId: g.keep.id,
+    duplicateIds: g.duplicates.map((r) => r.id),
+    count: g.all.length,
+    firstAt: g.all.map((r) => r.created_at).sort()[0] || null,
+    lastAt: g.all.map((r) => r.created_at).sort().at(-1) || null,
+    textSha256: sha12(String(g.keep.text_content || '')),
+  }));
+  return {
+    agent: target.agent,
+    dbPath: target.dbPath,
+    duplicateGroups: groups.length,
+    duplicateRows,
+    affectedConversations: conversations.size,
+    firstAt: first,
+    lastAt: last,
+    examples,
+  };
+}
+
+function makeBackup(db, dbPath, backupDir) {
+  const dir = backupDir ? resolve(backupDir) : dirname(dbPath);
+  mkdirSync(dir, { recursive: true });
+  const backupPath = join(dir, `${dbPath.split('/').pop()}.backup-${isoStamp()}`);
+  db.exec(`VACUUM INTO ${sqlLiteral(backupPath)}`);
+  return backupPath;
+}
+
+function runIntegrityChecks(db) {
+  const integrity = db.prepare('PRAGMA integrity_check').all().map((r) => Object.values(r)[0]);
+  const foreignKeys = db.prepare('PRAGMA foreign_key_check').all();
+  return { integrity, foreignKeys };
+}
+
+function assertChecksClean(checks) {
+  const integrityOk = checks.integrity.length === 1 && checks.integrity[0] === 'ok';
+  if (!integrityOk) throw new Error(`integrity_check failed: ${JSON.stringify(checks.integrity)}`);
+  if (checks.foreignKeys.length > 0) throw new Error(`foreign_key_check failed: ${JSON.stringify(checks.foreignKeys.slice(0, 20))}`);
+}
+
+function rewriteReferences(db, fromId, toId) {
+  if (tableExists(db, 'summary_messages')) {
+    db.prepare('INSERT OR IGNORE INTO summary_messages (summary_id, message_id) SELECT summary_id, ? FROM summary_messages WHERE message_id = ?').run(toId, fromId);
+    db.prepare('DELETE FROM summary_messages WHERE message_id = ?').run(fromId);
+  }
+  if (tableExists(db, 'messages') && columnExists(db, 'messages', 'parent_id')) {
+    db.prepare('UPDATE messages SET parent_id = ? WHERE parent_id = ?').run(toId, fromId);
+  }
+  if (tableExists(db, 'contexts') && columnExists(db, 'contexts', 'head_message_id')) {
+    db.prepare('UPDATE contexts SET head_message_id = ? WHERE head_message_id = ?').run(toId, fromId);
+  }
+  if (tableExists(db, 'composition_snapshots') && columnExists(db, 'composition_snapshots', 'head_message_id')) {
+    db.prepare('UPDATE composition_snapshots SET head_message_id = ? WHERE head_message_id = ?').run(toId, fromId);
+  }
+  if (tableExists(db, 'tool_artifacts') && columnExists(db, 'tool_artifacts', 'message_id')) {
+    db.prepare('UPDATE tool_artifacts SET message_id = ? WHERE message_id = ?').run(toId, fromId);
+  }
+
+  // Bridge rows are derived indexes. Drop duplicate-side rows; operators can run
+  // the bridge backfill later if they want to rebuild derived mentions exactly.
+  for (const table of ['message_entity_mentions', 'message_facet_mentions', 'entity_bridge_message_index']) {
+    if (tableExists(db, table) && columnExists(db, table, 'message_id')) {
+      db.prepare(`DELETE FROM ${table} WHERE message_id = ?`).run(fromId);
+    }
+  }
+}
+
+function applyGroups(db, groups) {
+  const affectedConversations = new Set();
+  let deleted = 0;
+  db.exec('PRAGMA foreign_keys = ON');
+  db.exec('BEGIN IMMEDIATE');
+  try {
+    for (const group of groups) {
+      const keepId = Number(group.keep.id);
+      affectedConversations.add(Number(group.keep.conversation_id));
+      for (const dup of group.duplicates) {
+        const dupId = Number(dup.id);
+        rewriteReferences(db, dupId, keepId);
+        const result = db.prepare('DELETE FROM messages WHERE id = ?').run(dupId);
+        deleted += Number(result.changes || 0);
+      }
+    }
+    if (tableExists(db, 'messages_fts')) {
+      db.prepare("INSERT INTO messages_fts(messages_fts) VALUES('rebuild')").run();
+    }
+    if (tableExists(db, 'conversations') && columnExists(db, 'conversations', 'message_count')) {
+      for (const conversationId of affectedConversations) {
+        db.prepare(`UPDATE conversations
+                      SET message_count = (SELECT COUNT(*) FROM messages WHERE conversation_id = ?),
+                          updated_at = COALESCE((SELECT MAX(created_at) FROM messages WHERE conversation_id = ?), updated_at)
+                    WHERE id = ?`).run(conversationId, conversationId, conversationId);
+      }
+    }
+    assertChecksClean(runIntegrityChecks(db));
+    db.exec('COMMIT');
+    return { deleted, affectedConversations: affectedConversations.size };
+  } catch (err) {
+    try { db.exec('ROLLBACK'); } catch {}
+    throw err;
+  }
+}
+
+async function main() {
+  const argv = parseArgs(process.argv.slice(2));
+  if (argv.help) {
+    usage();
+    return;
+  }
+  const apply = Boolean(argv.apply);
+  const json = Boolean(argv.json);
+  const exampleLimit = argv.examples === true ? 5 : Math.max(0, Number(argv.examples ?? 5));
+  const targets = resolveDbTargets({ dataDir: argv['data-dir'], dbPath: argv.db, agent: argv.agent });
+  const results = [];
+
+  for (const target of targets) {
+    const db = new DatabaseSync(target.dbPath);
+    try {
+      const groups = findStampedUserDuplicateGroups(db);
+      const summary = summarizeTarget(target, groups, exampleLimit);
+      summary.mode = 'stamped-user-replay-duplicates';
+      summary.dryRun = !apply;
+      if (apply && groups.length > 0) {
+        if (!argv['no-backup']) summary.backupPath = makeBackup(db, target.dbPath, argv['backup-dir']);
+        const applied = applyGroups(db, groups);
+        summary.deletedRows = applied.deleted;
+        summary.postApplyDuplicateGroups = findStampedUserDuplicateGroups(db).length;
+      }
+      results.push(summary);
+    } finally {
+      db.close();
+    }
+  }
+
+  const total = results.reduce((acc, r) => {
+    acc.duplicateGroups += r.duplicateGroups;
+    acc.duplicateRows += r.duplicateRows;
+    acc.deletedRows += r.deletedRows || 0;
+    return acc;
+  }, { duplicateGroups: 0, duplicateRows: 0, deletedRows: 0 });
+
+  const payload = { ok: true, dryRun: !apply, total, results };
+  if (json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log(`HyperMem cleanup ${apply ? 'apply' : 'dry-run'}: stamped user replay duplicates`);
+  console.log(`Targets: ${results.length}`);
+  console.log(`Duplicate groups: ${total.duplicateGroups}`);
+  console.log(`Duplicate rows: ${total.duplicateRows}`);
+  if (apply) console.log(`Deleted rows: ${total.deletedRows}`);
+  for (const r of results.filter((item) => item.duplicateRows > 0).slice(0, 20)) {
+    console.log(`- ${r.agent}: groups=${r.duplicateGroups} rows=${r.duplicateRows} first=${r.firstAt || 'n/a'} last=${r.lastAt || 'n/a'}`);
+    if (r.backupPath) console.log(`  backup=${r.backupPath}`);
+  }
+  if (!apply && total.duplicateRows > 0) {
+    console.log('\nNo changes made. Re-run with --apply to repair after stopping Gateway/OpenClaw writers.');
+  }
+}
+
+main().catch((err) => {
+  console.error(`hypermem-cleanup failed: ${err.message}`);
+  exit(1);
+});