@psiclawops/hypermem 0.9.1 → 0.9.3

package/dist/work-store.js

@@ -0,0 +1,273 @@
+/**
+ * hypermem Work Item Store
+ *
+ * Fleet kanban board in SQL. Replaces WORKQUEUE.md.
+ * Lives in the central library DB.
+ */
+function nowIso() {
+    return new Date().toISOString();
+}
+function parseItemRow(row) {
+    return {
+        id: row.id,
+        title: row.title,
+        description: row.description || null,
+        status: row.status,
+        priority: row.priority,
+        agentId: row.agent_id || null,
+        createdBy: row.created_by,
+        domain: row.domain || null,
+        parentId: row.parent_id || null,
+        blockedBy: row.blocked_by || null,
+        sessionKey: row.session_key || null,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        startedAt: row.started_at || null,
+        completedAt: row.completed_at || null,
+        dueAt: row.due_at || null,
+        metadata: row.metadata ? JSON.parse(row.metadata) : null,
+    };
+}
+function parseEventRow(row) {
+    return {
+        id: row.id,
+        workItemId: row.work_item_id,
+        eventType: row.event_type,
+        oldStatus: row.old_status || null,
+        newStatus: row.new_status || null,
+        agentId: row.agent_id || null,
+        comment: row.comment || null,
+        createdAt: row.created_at,
+    };
+}
+/**
+ * Generate a work item ID candidate.
+ * Uses a 6-hex random suffix (~16.7M daily space).
+ */
+function generateIdCandidate() {
+    const date = new Date().toISOString().slice(0, 10).replace(/-/g, '');
+    const suffix = Math.floor(Math.random() * 0xffffff).toString(16).padStart(6, '0');
+    return `WQ-${date}-${suffix}`;
+}
+export class WorkStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Create a new work item.
+     */
+    create(data) {
+        const now = nowIso();
+        // Use caller-supplied ID if provided, otherwise generate with retry-on-conflict.
+        // Random suffix collisions are rare but possible under bulk creation — retry
+        // up to 10 times before giving up. Each retry picks a new random suffix.
+        const callerSuppliedId = data.metadata?.id;
+        let id = callerSuppliedId || generateIdCandidate();
+        let attempts = 0;
+        while (attempts < 10) {
+            const existing = this.db
+                .prepare('SELECT id FROM work_items WHERE id = ?')
+                .get(id);
+            if (!existing)
+                break;
+            if (callerSuppliedId) {
+                throw new Error(`Work item ID already exists: ${id}`);
+            }
+            id = generateIdCandidate();
+            attempts++;
+        }
+        this.db.prepare(`
+      INSERT INTO work_items (id, title, description, status, priority, agent_id,
+        created_by, domain, parent_id, created_at, updated_at, due_at, metadata)
+      VALUES (?, ?, ?, 'incoming', ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, data.title, data.description || null, data.priority || 3, data.agentId || null, data.createdBy, data.domain || null, data.parentId || null, now, now, data.dueAt || null, data.metadata ? JSON.stringify(data.metadata) : null);
+        this.recordEvent(id, 'created', null, 'incoming', data.createdBy);
+        return this.getItem(id);
+    }
+    /**
+     * Update the status of a work item.
+     */
+    updateStatus(id, newStatus, agentId, comment) {
+        const now = nowIso();
+        const current = this.getItem(id);
+        if (!current)
+            return null;
+        const updates = ['status = ?', 'updated_at = ?'];
+        const params = [newStatus, now];
+        if (newStatus === 'active' && !current.startedAt) {
+            updates.push('started_at = ?');
+            params.push(now);
+        }
+        if (newStatus === 'completed' || newStatus === 'cancelled') {
+            updates.push('completed_at = ?');
+            params.push(now);
+        }
+        params.push(id);
+        this.db.prepare(`UPDATE work_items SET ${updates.join(', ')} WHERE id = ?`).run(...params);
+        this.recordEvent(id, 'status_changed', current.status, newStatus, agentId, comment);
+        return this.getItem(id);
+    }
+    /**
+     * Assign a work item to an agent.
+     */
+    assign(id, agentId, assignedBy) {
+        const now = nowIso();
+        this.db.prepare('UPDATE work_items SET agent_id = ?, updated_at = ? WHERE id = ?').run(agentId, now, id);
+        this.recordEvent(id, 'assigned', null, null, assignedBy, `Assigned to ${agentId}`);
+        return this.getItem(id);
+    }
+    /**
+     * Block a work item.
+     */
+    block(id, blockedBy, agentId, reason) {
+        const now = nowIso();
+        const current = this.getItem(id);
+        if (!current)
+            return null;
+        this.db.prepare("UPDATE work_items SET status = 'blocked', blocked_by = ?, updated_at = ? WHERE id = ?").run(blockedBy, now, id);
+        this.recordEvent(id, 'blocked', current.status, 'blocked', agentId, reason || `Blocked by ${blockedBy}`);
+        return this.getItem(id);
+    }
+    /**
+     * Get a work item by ID.
+     */
+    getItem(id) {
+        const row = this.db.prepare('SELECT * FROM work_items WHERE id = ?')
+            .get(id);
+        return row ? parseItemRow(row) : null;
+    }
+    /**
+     * Get active work for an agent.
+     */
+    getAgentWork(agentId, status) {
+        let sql = 'SELECT * FROM work_items WHERE agent_id = ?';
+        const params = [agentId];
+        if (status) {
+            sql += ' AND status = ?';
+            params.push(status);
+        }
+        else {
+            sql += " AND status NOT IN ('completed', 'cancelled')";
+        }
+        sql += ' ORDER BY priority, created_at';
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(parseItemRow);
+    }
+    /**
+     * Get the fleet kanban — all active work grouped by status.
+     */
+    getKanban(opts) {
+        let sql = "SELECT * FROM work_items WHERE status NOT IN ('completed', 'cancelled')";
+        const params = [];
+        if (opts?.domain) {
+            sql += ' AND domain = ?';
+            params.push(opts.domain);
+        }
+        if (opts?.agentId) {
+            sql += ' AND agent_id = ?';
+            params.push(opts.agentId);
+        }
+        sql += ' ORDER BY status, priority, created_at';
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(parseItemRow);
+    }
+    /**
+     * Get blocked items across the fleet.
+     */
+    getBlocked() {
+        const rows = this.db.prepare("SELECT * FROM work_items WHERE status = 'blocked' ORDER BY priority, created_at").all();
+        return rows.map(parseItemRow);
+    }
+    /**
+     * Get completion stats for the fleet.
+     */
+    getStats(opts) {
+        let sql = 'SELECT status, COUNT(*) as cnt FROM work_items';
+        const params = [];
+        const conditions = [];
+        if (opts?.agentId) {
+            conditions.push('agent_id = ?');
+            params.push(opts.agentId);
+        }
+        if (opts?.since) {
+            conditions.push('created_at >= ?');
+            params.push(opts.since);
+        }
+        if (conditions.length)
+            sql += ' WHERE ' + conditions.join(' AND ');
+        sql += ' GROUP BY status';
+        const rows = this.db.prepare(sql).all(...params);
+        const counts = {};
+        let total = 0;
+        for (const r of rows) {
+            counts[r.status] = r.cnt;
+            total += r.cnt;
+        }
+        // Avg duration for completed items
+        let avgSql = `
+      SELECT AVG(julianday(completed_at) - julianday(started_at)) * 24 as avg_hours
+      FROM work_items WHERE status = 'completed' AND started_at IS NOT NULL
+    `;
+        const avgParams = [];
+        if (opts?.agentId) {
+            avgSql += ' AND agent_id = ?';
+            avgParams.push(opts.agentId);
+        }
+        if (opts?.since) {
+            avgSql += ' AND completed_at >= ?';
+            avgParams.push(opts.since);
+        }
+        const avgRow = this.db.prepare(avgSql).get(...avgParams);
+        return {
+            total,
+            incoming: counts['incoming'] || 0,
+            active: counts['active'] || 0,
+            blocked: counts['blocked'] || 0,
+            review: counts['review'] || 0,
+            completed: counts['completed'] || 0,
+            cancelled: counts['cancelled'] || 0,
+            avgDurationHours: avgRow?.avg_hours || null,
+        };
+    }
+    /**
+     * Get events for a work item.
+     */
+    getEvents(workItemId, limit = 50) {
+        const rows = this.db.prepare('SELECT * FROM work_events WHERE work_item_id = ? ORDER BY created_at DESC LIMIT ?').all(workItemId, limit);
+        return rows.map(parseEventRow);
+    }
+    /**
+     * Search work items.
+     */
+    search(query, limit = 20) {
+        try {
+            const rows = this.db.prepare(`
+        SELECT w.* FROM work_items w
+        JOIN work_items_fts fts ON w.rowid = fts.rowid
+        WHERE work_items_fts MATCH ?
+        ORDER BY rank
+        LIMIT ?
+      `).all(query, limit);
+            return rows.map(parseItemRow);
+        }
+        catch {
+            // FTS fallback
+            const rows = this.db.prepare(`
+        SELECT * FROM work_items
+        WHERE title LIKE ? OR description LIKE ?
+        ORDER BY priority, created_at DESC
+        LIMIT ?
+      `).all(`%${query}%`, `%${query}%`, limit);
+            return rows.map(parseItemRow);
+        }
+    }
+    // ── Private helpers ─────────────────────────────────────────
+    recordEvent(workItemId, eventType, oldStatus, newStatus, agentId, comment) {
+        this.db.prepare(`
+      INSERT INTO work_events (work_item_id, event_type, old_status, new_status, agent_id, comment, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(workItemId, eventType, oldStatus, newStatus, agentId || null, comment || null, nowIso());
+    }
+}
+//# sourceMappingURL=work-store.js.map

package/docs/MEMORY_MD_AUTHORING.md

@@ -123,14 +123,14 @@ A simple operating rule works well:
 Bad:
 
 ```md
-- Forge runs copilot-local/claude-sonnet-4.6
+- Agent runs provider/model-X
 ```
 
 Better:
 
 ```md
-- Forge standard model was copilot-local/claude-sonnet-4.6 as of 2026-04-11; recheck after provider routing changes
-  → memory_search("Forge standard model 2026-04-11 provider routing")
+- Agent standard model was provider/model-X as of YYYY-MM-DD; recheck after provider routing changes
+  → memory_search("agent standard model YYYY-MM-DD provider routing")
 ```
 
 ## Relationship to daily memory files

package/docs/ROADMAP.md

@@ -197,8 +197,8 @@ Phase 5 stays important, but it is not the next sprint until the higher-priority
 | Strict topic mode legacy NULL backfill | 🟡 DEFERRED | Wait for stable topic coverage before running the migration/backfill. |
 | ACA Step 4 retrieval stubs replace static files | 🔲 PENDING | Still relevant, but downstream of lifecycle/diagnostics stability. Do not start from older ACA notes. |
 | ACA Step 5 governance context assembly | 🔲 PENDING | Still relevant, but depends on Step 4. Do not start until Step 4 has an accepted implementation contract. |
-| Tokenjuice + HyperMem tool-result pipeline integration | 🔲 TRIAGE | OpenClaw 2026.4.24 ships `tokenjuice`, a deterministic rule-based tool-result pre-trim hook (collapses ANSI/build noise/repeated frames). It and HyperMem's size-based `tool_result_trim` both fire on tool results. Three integration concerns before fleet-wide enable: (1) **Hook ordering**: tokenjuice must run before HyperMem trim so HyperMem only collapses what tokenjuice cannot already remove deterministically. Reverse order wastes savings. (2) **Tool-artifact store**: HyperMem's L4 durable artifact store must capture the **untransformed** tool result, not the tokenjuice-trimmed one. The hook chain should pass `{ raw, transformed }` so artifacts get `raw` while message stream gets `transformed`. (3) **Telemetry**: unify `tool_result_trim_event` schema with `source: "tokenjuice" \| "hypermem"` and per-turn rollup so operators see one report. Sequencing: pilot tokenjuice standalone on one heavy-exec agent (HyperBuilder generator candidate) to measure rule-trim savings on our actual workloads before formalizing the contract. Do not write the contract before we have numbers. Surfaced 2026-04-25 by ragesaq. |
-| Codex harness compatibility for HyperMem hooks | 🔲 TRIAGE | OpenClaw is generalizing the embedded executor (PI stays default; Codex is a registered plugin harness via `agents.defaults.embeddedHarness`). When a turn runs through the Codex harness, OpenClaw owns mirror transcript + tool dispatch but Codex owns the agent loop and native compaction. Investigate before any agent moves off PI: (1) whether HyperMem's `before_prompt_build`, `before_compaction`, `after_compaction`, `before_message_write`, `llm_input`, `llm_output`, `agent_end`, `after_tool_call` hooks fire with the same timing on Codex turns; (2) collision between HyperCompositor compaction and Codex native app-server compaction (need an explicit disable on one side or a coordination contract); (3) whether the locally mirrored transcript loses any content the indexer assumes is present; (4) `subagent` `context: "fork"` behavior when parent runs on Codex (parent JSONL is mirror, not source of truth); (5) keep `openai-codex/*` provider routes (PI under the hood) distinct from `codex/*` runtime selection (Codex harness). Pilot on one non-critical agent with `runtime: "codex"`, `fallback: "pi"` once the parity gap closes; do not adopt fleet-wide before then. Surfaced 2026-04-24 by ragesaq. |
+| Tokenjuice + HyperMem tool-result pipeline integration | 🔲 TRIAGE | OpenClaw 2026.4.24 ships `tokenjuice`, a deterministic rule-based tool-result pre-trim hook (collapses ANSI/build noise/repeated frames). It and HyperMem's size-based `tool_result_trim` both fire on tool results. Three integration concerns before fleet-wide enable: (1) **Hook ordering**: tokenjuice must run before HyperMem trim so HyperMem only collapses what tokenjuice cannot already remove deterministically. Reverse order wastes savings. (2) **Tool-artifact store**: HyperMem's L4 durable artifact store must capture the **untransformed** tool result, not the tokenjuice-trimmed one. The hook chain should pass `{ raw, transformed }` so artifacts get `raw` while message stream gets `transformed`. (3) **Telemetry**: unify `tool_result_trim_event` schema with `source: "tokenjuice" \| "hypermem"` and per-turn rollup so operators see one report. Sequencing: pilot tokenjuice standalone on one heavy-exec agent (HyperBuilder generator candidate) to measure rule-trim savings on our actual workloads before formalizing the contract. Do not write the contract before we have numbers. Surfaced 2026-04-25 during operator review. |
+| Codex harness compatibility for HyperMem hooks | 🔲 TRIAGE | OpenClaw is generalizing the embedded executor (PI stays default; Codex is a registered plugin harness via `agents.defaults.embeddedHarness`). When a turn runs through the Codex harness, OpenClaw owns mirror transcript + tool dispatch but Codex owns the agent loop and native compaction. Investigate before any agent moves off PI: (1) whether HyperMem's `before_prompt_build`, `before_compaction`, `after_compaction`, `before_message_write`, `llm_input`, `llm_output`, `agent_end`, `after_tool_call` hooks fire with the same timing on Codex turns; (2) collision between HyperCompositor compaction and Codex native app-server compaction (need an explicit disable on one side or a coordination contract); (3) whether the locally mirrored transcript loses any content the indexer assumes is present; (4) `subagent` `context: "fork"` behavior when parent runs on Codex (parent JSONL is mirror, not source of truth); (5) keep `openai-codex/*` provider routes (PI under the hood) distinct from `codex/*` runtime selection (Codex harness). Pilot on one non-critical agent with `runtime: "codex"`, `fallback: "pi"` once the parity gap closes; do not adopt fleet-wide before then. Surfaced 2026-04-24 during operator review. |
 
 ---
 

package/install.sh

@@ -18,6 +18,7 @@ CONFIG_FILE="$HOME/.openclaw/hypermem/config.json"
 ASSUME_YES=false
 SKIP_NPM=false
 SKIP_STAGE=false
+DRY_RUN=false
 
 usage() {
   cat <<EOF
@@ -32,6 +33,7 @@ Options:
   --runtime-dir <p>  staged OpenClaw runtime dir, default: ~/.openclaw/plugins/hypermem
   --skip-npm         use existing package in install dir
   --skip-stage       install package only, do not run hypermem-install
+  --dry-run          print planned actions without installing, staging, or writing config
   --help             show this help
 
 Environment overrides:
@@ -49,6 +51,7 @@ while [[ $# -gt 0 ]]; do
     --runtime-dir) RUNTIME_DIR="$2"; shift 2 ;;
     --skip-npm) SKIP_NPM=true; shift ;;
     --skip-stage) SKIP_STAGE=true; shift ;;
+    --dry-run) DRY_RUN=true; shift ;;
     --help|-h) usage; exit 0 ;;
     *) echo -e "${RED}Unknown option:${NC} $1" >&2; usage; exit 1 ;;
   esac
@@ -57,6 +60,7 @@ done
 info() { echo -e "  ${CYAN}→${NC} $*"; }
 success() { echo -e "  ${GREEN}✓${NC} $*"; }
 warn() { echo -e "  ${YELLOW}⚠${NC}  $*"; }
+dryrun() { echo -e "  ${YELLOW}DRY-RUN${NC} $*"; }
 die() { echo -e "  ${RED}✗${NC} $*" >&2; exit 1; }
 
 confirm() {
@@ -86,6 +90,10 @@ preflight() {
   command -v npm >/dev/null 2>&1 || die "npm is required"
   success "npm $(npm --version)"
 
+  if $DRY_RUN; then
+    warn "dry-run mode: no package install, runtime staging, config write, or gateway change will be performed"
+  fi
+
   if command -v openclaw >/dev/null 2>&1; then
     success "openclaw CLI found"
     openclaw gateway status >/dev/null 2>&1 || warn "OpenClaw gateway is not running or not onboarded yet. Complete OpenClaw setup before activation."
@@ -96,6 +104,12 @@ preflight() {
 
 install_package() {
   echo -e "\n${BOLD}  Package install${NC}"
+  if $DRY_RUN; then
+    dryrun "would create/install package directory: $INSTALL_DIR"
+    dryrun "would install package: $PACKAGE"
+    return
+  fi
+
   mkdir -p "$INSTALL_DIR"
   if [[ ! -f "$INSTALL_DIR/package.json" ]]; then
     info "initializing $INSTALL_DIR"
@@ -114,6 +128,11 @@ install_package() {
 }
 
 backup_runtime() {
+  if $DRY_RUN; then
+    dryrun "would check for existing runtime and optionally back up: $RUNTIME_DIR"
+    return 0
+  fi
+
   [[ -e "$RUNTIME_DIR" ]] || return 0
   local backup
   backup="${RUNTIME_DIR}.backup.$(date +%Y%m%d-%H%M%S)"
@@ -132,6 +151,11 @@ stage_runtime() {
     return
   fi
 
+  if $DRY_RUN; then
+    dryrun "would run runtime installer into: $RUNTIME_DIR"
+    return
+  fi
+
   local installer="$INSTALL_DIR/node_modules/@psiclawops/hypermem/scripts/install-runtime.mjs"
   [[ -f "$installer" ]] || die "missing runtime installer: $installer"
   backup_runtime
@@ -141,6 +165,11 @@ stage_runtime() {
 
 write_minimal_config_if_missing() {
   echo -e "\n${BOLD}  Config check${NC}"
+  if $DRY_RUN; then
+    dryrun "would preserve existing config or write lightweight starter config: $CONFIG_FILE"
+    return
+  fi
+
   if [[ -f "$CONFIG_FILE" ]]; then
     success "existing config preserved: $CONFIG_FILE"
     return
@@ -210,6 +239,11 @@ JSON
 
 verify_stage() {
   echo -e "\n${BOLD}  Stage verification${NC}"
+  if $DRY_RUN; then
+    dryrun "would verify runtime payload under: $RUNTIME_DIR"
+    return
+  fi
+
   [[ -d "$RUNTIME_DIR/dist" ]] || die "missing $RUNTIME_DIR/dist"
   [[ -d "$RUNTIME_DIR/plugin/dist" ]] || die "missing $RUNTIME_DIR/plugin/dist"
   [[ -d "$RUNTIME_DIR/memory-plugin/dist" ]] || die "missing $RUNTIME_DIR/memory-plugin/dist"

package/memory-plugin/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * HyperMem Memory Plugin
+ *
+ * Thin adapter that bridges HyperMem's retrieval capabilities into
+ * OpenClaw's memory slot contract (`kind: "memory"`).
+ *
+ * The context engine plugin (hypercompositor) owns the full lifecycle:
+ * ingest, assemble, compact, afterTurn, bootstrap, dispose.
+ *
+ * This plugin owns the memory slot contract:
+ * - registerMemoryCapability() with runtime + publicArtifacts
+ * - memory_search tool backing via MemorySearchManager
+ * - Public artifacts for memory-wiki bridge
+ *
+ * Both plugins share the same HyperMem singleton (loaded from repo dist).
+ */
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: import("openclaw/plugin-sdk").OpenClawPluginConfigSchema;
+    register: NonNullable<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["register"]>;
+} & Pick<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition, "kind" | "reload" | "nodeHostCommands" | "securityAuditCollectors">;
+export default _default;