@unblocklabs/unblock-memory 0.1.1 → 0.1.2

package/dist/src/analysis.d.ts

@@ -1,8 +1,4 @@
 import type { QMDStore } from "@unblocklabs/qmd";
-export declare const DEFAULT_CLUSTER_LIMIT = 20;
-export declare const MAX_CLUSTER_LIMIT = 50;
-export declare const DEFAULT_MEMBER_LIMIT = 20;
-export declare const MAX_MEMBER_LIMIT = 50;
 type AnalysisDatabase = QMDStore["internal"]["db"];
 export type MemoryReclusterOptions = {
     space?: {
@@ -26,7 +22,7 @@ export type AnalysisRunner = (params: {
     options?: MemoryReclusterOptions;
     signal?: AbortSignal;
 }) => Promise<void>;
-export type MemoryAnalysisMember = {
+type MemoryAnalysisMember = {
     hash: string;
     seq: number;
     probability: number;
@@ -52,7 +48,7 @@ export type MemoryAnalysisSummary = {
     stale: boolean;
     staleSince: string | null;
 };
-export type MemoryClusterSummary = {
+type MemoryClusterSummary = {
     clusterId: string;
     size: number;
     availableSize: number;

package/dist/src/analysis.js

@@ -1,9 +1,9 @@
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
-export const DEFAULT_CLUSTER_LIMIT = 20;
-export const MAX_CLUSTER_LIMIT = 50;
-export const DEFAULT_MEMBER_LIMIT = 20;
-export const MAX_MEMBER_LIMIT = 50;
+const DEFAULT_CLUSTER_LIMIT = 20;
+const MAX_CLUSTER_LIMIT = 50;
+const DEFAULT_MEMBER_LIMIT = 20;
+const MAX_MEMBER_LIMIT = 50;
 const MAX_EXCERPT_BYTES = 2_000;
 const MAX_TOTAL_EXCERPT_BYTES = 12_000;
 const MAX_ALIASES_PER_MEMBER = 5;
@@ -47,6 +47,19 @@ export function ensureMemoryAnalysisSchema(db) {
 
     CREATE INDEX IF NOT EXISTS idx_memory_analysis_memberships_cluster
       ON memory_analysis_memberships(run_id, cluster_id, representative_rank);
+
+    CREATE VIEW IF NOT EXISTS memory_analysis_available_memberships AS
+    SELECT
+      m.run_id, m.hash, m.seq, m.cluster_id, m.probability, m.outlier_score,
+      m.x, m.y, m.representative_rank, cv.pos, cv.chunk_len, c.doc
+    FROM memory_analysis_memberships m
+    JOIN content_vectors cv ON cv.hash = m.hash AND cv.seq = m.seq
+    JOIN content c ON c.hash = m.hash
+    WHERE EXISTS (
+      SELECT 1
+      FROM documents d
+      WHERE d.hash = m.hash AND d.active = 1
+    );
   `);
 }
 export function markMemoryAnalysisStale(db) {
@@ -137,10 +150,7 @@ export function latestAnalysisRunId(db) {
 function count(db, sql, runId) {
     return db.prepare(sql).get(runId)?.count ?? 0;
 }
-export function readAnalysisSummary(db) {
-    const run = latestRun(db);
-    if (!run)
-        return undefined;
+function analysisSummary(db, run) {
     const clusters = count(db, "SELECT COUNT(*) AS count FROM memory_analysis_clusters WHERE run_id = ?", run.id);
     const members = count(db, "SELECT COUNT(*) AS count FROM memory_analysis_memberships WHERE run_id = ?", run.id);
     const expectedNonNoise = count(db, "SELECT COALESCE(SUM(size), 0) AS count FROM memory_analysis_clusters WHERE run_id = ?", run.id);
@@ -171,6 +181,14 @@ export function readAnalysisSummary(db) {
         staleSince: run.stale_at,
     };
 }
+export function readAnalysisSummary(db) {
+    const run = latestRun(db);
+    return run ? analysisSummary(db, run) : undefined;
+}
+function latestValidRun(db) {
+    const run = latestRun(db);
+    return run && analysisSummary(db, run) ? run : undefined;
+}
 function sourcePaths(db, hash, limit) {
     if (limit <= 0)
         return [];
@@ -202,16 +220,9 @@ function members(db, runId, clusterId, limit, maxExcerptBytes = MAX_EXCERPT_BYTE
     const rows = db.prepare(`
     SELECT
       m.hash, m.seq, m.probability, m.outlier_score, m.x, m.y,
-      m.representative_rank, cv.pos, cv.chunk_len, c.doc
-    FROM memory_analysis_memberships m
-    JOIN content_vectors cv ON cv.hash = m.hash AND cv.seq = m.seq
-    JOIN content c ON c.hash = m.hash
+      m.representative_rank, m.pos, m.chunk_len, m.doc
+    FROM memory_analysis_available_memberships m
     WHERE m.run_id = ? AND m.cluster_id = ?
-      AND EXISTS (
-        SELECT 1
-        FROM documents d
-        WHERE d.hash = m.hash AND d.active = 1
-      )
     ORDER BY ${noiseOrder}
     LIMIT ?
   `).all(runId, clusterId, limit);
@@ -240,15 +251,8 @@ function members(db, runId, clusterId, limit, maxExcerptBytes = MAX_EXCERPT_BYTE
 function availableSize(db, runId, clusterId) {
     return db.prepare(`
     SELECT COUNT(*) AS count
-    FROM memory_analysis_memberships m
-    JOIN content_vectors cv ON cv.hash = m.hash AND cv.seq = m.seq
-    JOIN content c ON c.hash = m.hash
-    WHERE m.run_id = ? AND m.cluster_id = ?
-      AND EXISTS (
-        SELECT 1
-        FROM documents d
-        WHERE d.hash = m.hash AND d.active = 1
-      )
+    FROM memory_analysis_available_memberships
+    WHERE run_id = ? AND cluster_id = ?
   `).get(runId, clusterId)?.count ?? 0;
 }
 function readMetadata(run) {
@@ -295,22 +299,20 @@ function noiseRow(db, runId) {
     SELECT
       -1 AS cluster_id,
       COUNT(*) AS size,
-      COUNT(CASE WHEN cv.hash IS NOT NULL AND c.hash IS NOT NULL AND EXISTS (
-        SELECT 1
-        FROM documents d
-        WHERE d.hash = m.hash AND d.active = 1
-      ) THEN 1 END) AS available_size,
+      (
+        SELECT COUNT(*)
+        FROM memory_analysis_available_memberships available
+        WHERE available.run_id = ? AND available.cluster_id = -1
+      ) AS available_size,
       COALESCE(AVG(m.probability), 0) AS mean_probability
     FROM memory_analysis_memberships m
-    LEFT JOIN content_vectors cv ON cv.hash = m.hash AND cv.seq = m.seq
-    LEFT JOIN content c ON c.hash = m.hash
     WHERE m.run_id = ? AND m.cluster_id = -1
     HAVING COUNT(*) > 0
-  `).get(runId);
+  `).get(runId, runId);
 }
 export function readClusters(db, requestedLimit = DEFAULT_CLUSTER_LIMIT) {
-    const run = latestRun(db);
-    if (!run || !readAnalysisSummary(db)) {
+    const run = latestValidRun(db);
+    if (!run) {
         return { status: "not_analyzed", ...readMetadata(), clusters: [], noise: null };
     }
     const limit = Math.max(1, Math.min(MAX_CLUSTER_LIMIT, Math.floor(requestedLimit)));
@@ -318,19 +320,14 @@ export function readClusters(db, requestedLimit = DEFAULT_CLUSTER_LIMIT) {
     SELECT
       c.cluster_id,
       c.size,
-      COUNT(CASE WHEN cv.hash IS NOT NULL AND content_row.hash IS NOT NULL AND EXISTS (
-        SELECT 1
-        FROM documents d
-        WHERE d.hash = m.hash AND d.active = 1
-      ) THEN 1 END) AS available_size,
+      (
+        SELECT COUNT(*)
+        FROM memory_analysis_available_memberships available
+        WHERE available.run_id = c.run_id AND available.cluster_id = c.cluster_id
+      ) AS available_size,
       c.mean_probability
     FROM memory_analysis_clusters c
-    LEFT JOIN memory_analysis_memberships m
-      ON m.run_id = c.run_id AND m.cluster_id = c.cluster_id
-    LEFT JOIN content_vectors cv ON cv.hash = m.hash AND cv.seq = m.seq
-    LEFT JOIN content content_row ON content_row.hash = m.hash
     WHERE c.run_id = ?
-    GROUP BY c.cluster_id, c.size, c.mean_probability
     ORDER BY c.size DESC, c.cluster_id
     LIMIT ?
   `).all(run.id, limit);
@@ -366,8 +363,8 @@ function resolveClusterId(db, runId, reference) {
     return clusterIds.find((row) => clusterReference(runId, row.cluster_id) === reference)?.cluster_id;
 }
 export function readCluster(db, clusterReferenceId, requestedLimit = DEFAULT_MEMBER_LIMIT) {
-    const run = latestRun(db);
-    if (!run || !readAnalysisSummary(db)) {
+    const run = latestValidRun(db);
+    if (!run) {
         return { status: "not_analyzed", ...readMetadata() };
     }
     const metadata = readMetadata(run);

package/dist/src/plugin.js

@@ -1,5 +1,6 @@
 import { Type } from "typebox";
-import { jsonResult, readStringParam } from "openclaw/plugin-sdk/agent-runtime";
+import { Value } from "typebox/value";
+import { jsonResult } from "openclaw/plugin-sdk/agent-runtime";
 import { resolveConfig } from "./config.js";
 import { QmdMemoryRuntime } from "./runtime.js";
 function getContext(ctx) {
@@ -8,11 +9,16 @@ function getContext(ctx) {
         return undefined;
     return { cfg, agentId: ctx.agentId };
 }
-function toolParams(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value)
-        ? Object.fromEntries(Object.entries(value))
-        : {};
-}
+const searchParameters = Type.Object({
+    query: Type.String({ pattern: "\\S" }),
+    maxResults: Type.Optional(Type.Integer({ minimum: 1, maximum: 20 })),
+    minScore: Type.Optional(Type.Number({ minimum: 0, maximum: 1 })),
+}, { additionalProperties: false });
+const getParameters = Type.Object({
+    path: Type.String({ pattern: "\\S" }),
+    from: Type.Optional(Type.Integer({ minimum: 1 })),
+    lines: Type.Optional(Type.Integer({ minimum: 1, maximum: 1000 })),
+}, { additionalProperties: false });
 function createSearchTool(runtime, ctx) {
     const active = getContext(ctx);
     if (!active)
@@ -21,18 +27,10 @@ function createSearchTool(runtime, ctx) {
         name: "memory_search",
         label: "Memory Search",
         description: "Search canonical Markdown memory with semantic vector retrieval.",
-        parameters: Type.Object({
-            query: Type.String(),
-            maxResults: Type.Optional(Type.Integer({ minimum: 1, maximum: 20 })),
-            minScore: Type.Optional(Type.Number({ minimum: 0, maximum: 1 })),
-        }),
+        parameters: searchParameters,
         async execute(_toolCallId, params, signal) {
-            const raw = toolParams(params);
-            const query = readStringParam(raw, "query");
-            if (!query)
-                throw new Error("query is required");
-            const maxResults = typeof raw.maxResults === "number" ? raw.maxResults : undefined;
-            const minScore = typeof raw.minScore === "number" ? raw.minScore : undefined;
+            const { query: untrimmedQuery, maxResults, minScore } = Value.Parse(searchParameters, params);
+            const query = untrimmedQuery.trim();
             const { manager, error } = await runtime.getMemorySearchManager(active);
             if (!manager)
                 return jsonResult({ results: [], error: error ?? "memory unavailable" });
@@ -49,23 +47,17 @@ function createGetTool(runtime, ctx) {
         name: "memory_get",
         label: "Memory Get",
         description: "Read an exact qmd:// path returned by memory_search.",
-        parameters: Type.Object({
-            path: Type.String(),
-            from: Type.Optional(Type.Integer({ minimum: 1 })),
-            lines: Type.Optional(Type.Integer({ minimum: 1, maximum: 1000 })),
-        }),
+        parameters: getParameters,
         async execute(_toolCallId, params) {
-            const raw = toolParams(params);
-            const path = readStringParam(raw, "path");
-            if (!path)
-                throw new Error("path is required");
+            const { path: untrimmedPath, from, lines } = Value.Parse(getParameters, params);
+            const path = untrimmedPath.trim();
             const { manager, error } = await runtime.getMemorySearchManager(active);
             if (!manager)
                 return jsonResult({ status: "unavailable", error: error ?? "memory unavailable" });
             return jsonResult(await manager.readFile({
                 relPath: path,
-                from: typeof raw.from === "number" ? raw.from : undefined,
-                lines: typeof raw.lines === "number" ? raw.lines : undefined,
+                from,
+                lines,
             }));
         },
     };
@@ -86,80 +78,6 @@ const reclusterParameters = Type.Object({
     }, { additionalProperties: false })),
     seed: Type.Optional(Type.Integer({ minimum: 0, maximum: 4_294_967_295 })),
 }, { additionalProperties: false });
-function requireObject(value, name) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        throw new Error(`${name} must be an object`);
-    }
-    return Object.fromEntries(Object.entries(value));
-}
-function optionalNumber(value, key, constraints) {
-    const candidate = value[key];
-    if (candidate === undefined)
-        return undefined;
-    const valid = typeof candidate === "number" && Number.isFinite(candidate) &&
-        candidate >= constraints.minimum &&
-        (constraints.maximum === undefined || candidate <= constraints.maximum) &&
-        (!constraints.integer || Number.isInteger(candidate));
-    if (!valid)
-        throw new Error(`${key} is invalid`);
-    return candidate;
-}
-function requireOnlyKeys(value, allowed) {
-    const unexpected = Object.keys(value).find((key) => !allowed.includes(key));
-    if (unexpected)
-        throw new Error(`${unexpected} is not allowed`);
-}
-function parseReclusterOptions(params) {
-    const raw = toolParams(params);
-    requireOnlyKeys(raw, ["space", "hdbscan", "seed"]);
-    const options = {};
-    if (raw.space !== undefined) {
-        const space = requireObject(raw.space, "space");
-        requireOnlyKeys(space, ["method", "nComponents", "nNeighbors", "minDist"]);
-        const method = space.method;
-        if (method !== undefined && method !== "umap" && method !== "none") {
-            throw new Error("space.method is invalid");
-        }
-        options.space = {
-            ...(method === undefined ? {} : { method }),
-            ...optionalEntry("nComponents", optionalNumber(space, "nComponents", { minimum: 2, maximum: 100, integer: true })),
-            ...optionalEntry("nNeighbors", optionalNumber(space, "nNeighbors", { minimum: 2, maximum: 200, integer: true })),
-            ...optionalEntry("minDist", optionalNumber(space, "minDist", { minimum: 0, maximum: 1 })),
-        };
-    }
-    if (raw.hdbscan !== undefined) {
-        const hdbscan = requireObject(raw.hdbscan, "hdbscan");
-        requireOnlyKeys(hdbscan, [
-            "minClusterSize",
-            "minSamples",
-            "clusterSelectionMethod",
-            "clusterSelectionEpsilon",
-            "allowSingleCluster",
-        ]);
-        const method = hdbscan.clusterSelectionMethod;
-        if (method !== undefined && method !== "eom" && method !== "leaf") {
-            throw new Error("hdbscan.clusterSelectionMethod is invalid");
-        }
-        const allowSingleCluster = hdbscan.allowSingleCluster;
-        if (allowSingleCluster !== undefined && typeof allowSingleCluster !== "boolean") {
-            throw new Error("hdbscan.allowSingleCluster is invalid");
-        }
-        options.hdbscan = {
-            ...optionalEntry("minClusterSize", optionalNumber(hdbscan, "minClusterSize", { minimum: 2, maximum: 100_000, integer: true })),
-            ...optionalEntry("minSamples", optionalNumber(hdbscan, "minSamples", { minimum: 1, maximum: 100_000, integer: true })),
-            ...(method === undefined ? {} : { clusterSelectionMethod: method }),
-            ...optionalEntry("clusterSelectionEpsilon", optionalNumber(hdbscan, "clusterSelectionEpsilon", { minimum: 0 })),
-            ...(allowSingleCluster === undefined ? {} : { allowSingleCluster }),
-        };
-    }
-    const seed = optionalNumber(raw, "seed", { minimum: 0, maximum: 4_294_967_295, integer: true });
-    if (seed !== undefined)
-        options.seed = seed;
-    return options;
-}
-function optionalEntry(key, value) {
-    return value === undefined ? {} : { [key]: value };
-}
 function createReclusterTool(runtime, ctx) {
     const active = getContext(ctx);
     if (!active)
@@ -170,7 +88,7 @@ function createReclusterTool(runtime, ctx) {
         description: "Rebuild memory clusters from existing QMD vectors. Call only when memory_list_clusters reports missing or stale analysis.",
         parameters: reclusterParameters,
         async execute(_toolCallId, params, signal) {
-            const options = parseReclusterOptions(params);
+            const options = Value.Parse(reclusterParameters, params);
             const { manager, error } = await runtime.getMemorySearchManager(active);
             if (!manager)
                 return jsonResult({ status: "unavailable", error: error ?? "memory unavailable" });
@@ -186,6 +104,9 @@ function createReclusterTool(runtime, ctx) {
         },
     };
 }
+const listClustersParameters = Type.Object({
+    limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 50 })),
+}, { additionalProperties: false });
 function createListClustersTool(runtime, ctx) {
     const active = getContext(ctx);
     if (!active)
@@ -194,13 +115,9 @@ function createListClustersTool(runtime, ctx) {
         name: "memory_list_clusters",
         label: "List Memory Clusters",
         description: "List current memory clusters and freshness. Call this before memory_recluster or memory_fetch_cluster.",
-        parameters: Type.Object({
-            limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 50 })),
-        }, { additionalProperties: false }),
+        parameters: listClustersParameters,
         async execute(_toolCallId, params) {
-            const raw = toolParams(params);
-            requireOnlyKeys(raw, ["limit"]);
-            const limit = optionalNumber(raw, "limit", { minimum: 1, maximum: 50, integer: true });
+            const { limit } = Value.Parse(listClustersParameters, params);
             const { manager, error } = await runtime.getMemorySearchManager(active);
             if (!manager)
                 return jsonResult({ status: "unavailable", error: error ?? "memory unavailable" });
@@ -208,6 +125,10 @@ function createListClustersTool(runtime, ctx) {
         },
     };
 }
+const fetchClusterParameters = Type.Object({
+    clusterId: Type.String({ pattern: "^[0-9a-f]{10}$" }),
+    topK: Type.Optional(Type.Integer({ minimum: 1, maximum: 50 })),
+}, { additionalProperties: false });
 function createFetchClusterTool(runtime, ctx) {
     const active = getContext(ctx);
     if (!active)
@@ -216,17 +137,9 @@ function createFetchClusterTool(runtime, ctx) {
         name: "memory_fetch_cluster",
         label: "Fetch Memory Cluster",
         description: "Fetch the top representative QMD chunks for a clusterId returned by memory_list_clusters.",
-        parameters: Type.Object({
-            clusterId: Type.String({ pattern: "^[0-9a-f]{10}$" }),
-            topK: Type.Optional(Type.Integer({ minimum: 1, maximum: 50 })),
-        }, { additionalProperties: false }),
+        parameters: fetchClusterParameters,
         async execute(_toolCallId, params) {
-            const raw = toolParams(params);
-            requireOnlyKeys(raw, ["clusterId", "topK"]);
-            const clusterId = readStringParam(raw, "clusterId");
-            if (!clusterId || !/^[0-9a-f]{10}$/.test(clusterId))
-                throw new Error("clusterId is invalid");
-            const topK = optionalNumber(raw, "topK", { minimum: 1, maximum: 50, integer: true });
+            const { clusterId, topK } = Value.Parse(fetchClusterParameters, params);
             const { manager, error } = await runtime.getMemorySearchManager(active);
             if (!manager)
                 return jsonResult({ status: "unavailable", error: error ?? "memory unavailable" });

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "unblock-memory",
   "name": "Unblock Memory",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Indexes, retrieves, and analyzes configured workspace memory with existing QMD vectors.",
   "kind": "memory",
   "activation": { "onStartup": false },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unblocklabs/unblock-memory",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Workspace-native memory for OpenClaw, powered by QMD",
   "type": "module",
   "license": "MIT",
@@ -22,11 +22,12 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "knip": "knip --reporter compact",
     "test": "node --import tsx --test --test-concurrency=1 tests/**/*.test.ts",
     "plugin:inspect": "plugin-inspector check --config plugin-inspector.config.json --no-openclaw",
     "plugin:inspect:runtime": "plugin-inspector check --config plugin-inspector.config.json --no-openclaw --runtime --mock-sdk --allow-execute",
     "release:check": "node scripts/check-release-version.mjs",
-    "preflight": "npm run build && npm run typecheck && npm test && npm run plugin:inspect && npm run plugin:inspect:runtime && npm pack --dry-run"
+    "preflight": "npm run knip && npm run build && npm run typecheck && npm test && npm run plugin:inspect && npm run plugin:inspect:runtime && npm pack --dry-run"
   },
   "dependencies": {
     "@unblocklabs/qmd": "github:unblocklabs-ai/qmd#0a6b15d",
@@ -38,6 +39,7 @@
     "@openclaw/plugin-inspector": "^0.3.10",
     "@types/node": "^24.6.0",
     "@types/picomatch": "^4.0.2",
+    "knip": "^6.32.2",
     "openclaw": "2026.8.1-beta.3",
     "tsx": "^4.20.6",
     "typescript": "^5.9.3"