@unblocklabs/unblock-memory 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Unblock Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# Unblock Memory
+
+Workspace-native memory for OpenClaw, powered internally by `@unblocklabs/qmd`.
+It keeps one warm QMD store per agent and exposes the standard `memory_search`
+and `memory_get` tools. Search uses semantic chunking v2 and QMD vsearch without
+a reranker.
+
+Optional memory analysis uses those same stored vectors in the same SQLite
+index. It does not re-embed memory, copy vectors, or create another database.
+
+## Installation
+
+From npm:
+
+```bash
+openclaw plugins install @unblocklabs/unblock-memory
+```
+
+Or directly from GitHub:
+
+```bash
+openclaw plugins install git:github.com/unblocklabs-ai/unblock-memory
+```
+
+## Configuration
+
+Select the plugin as the memory provider and list any exact Markdown files,
+directories, or globs to index:
+
+```json5
+{
+  plugins: {
+    slots: { memory: "unblock-memory" },
+    entries: {
+      "unblock-memory": {
+        config: {
+          paths: [
+            "MEMORY.md",
+            "USER.md",
+            "memory/**/*.md",
+            "/absolute/shared/**/*.md",
+          ],
+          analysis: {
+            executable: "/absolute/path/to/unblock-memory-analysis",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Relative entries resolve from each agent workspace. Absolute paths and `~/`
+paths are supported. A directory means recursive Markdown. When `paths` is
+omitted, the defaults are `MEMORY.md`, `USER.md`, and `memory/**/*.md`; an
+explicit array replaces those defaults.
+
+Indexes live at `~/.openclaw/agents/<agentId>/unblock-memory/index.sqlite` (or the
+equivalent configured OpenClaw state directory). The first lookup builds the
+index; Markdown filesystem changes queue a debounced, serialized background
+refresh.
+
+## Memory analysis
+
+Analysis is opt-in and requires the separately installed local analysis worker.
+Set `analysis.executable` to its absolute path. The plugin invokes that file
+directly with `--db <the agent's known index path>` and, when requested,
+`--config-json <validated clustering options>`. Agents cannot choose a database,
+executable, shell command, or arbitrary arguments.
+
+The analysis worker reads QMD's existing semantic vectors and writes only
+derived results into three namespaced tables in that same `index.sqlite`:
+
+- `memory_analysis_runs`
+- `memory_analysis_clusters`
+- `memory_analysis_memberships`
+
+Unblock Memory exposes:
+
+- `memory_list_clusters` to cheaply list current clusters and report whether the
+  retained analysis is stale
+- `memory_recluster` to explicitly rebuild clusters when the list is missing or stale
+- `memory_fetch_cluster` to return up to `topK` representative QMD chunks for a
+  short `clusterId` returned by `memory_list_clusters`
+
+`memory_recluster` optionally accepts UMAP controls (`method`, components,
+neighbors, and minimum distance), HDBSCAN controls (minimum cluster size,
+minimum samples, selection method and epsilon, and single-cluster behavior),
+and a deterministic seed. Omitting them uses the worker's defaults.
+
+Cluster reads return at most 50 members. Member excerpts are capped at 2 KB
+each and 12 KB across a response; source aliases are capped at five per member
+and 50 across a response.
+
+If indexing changes content or vectors, the previous derived analysis is kept
+and marked stale. Cluster reads include the analysis timestamp, stale timestamp,
+and a hint to call `memory_recluster`; unavailable chunks reduce `availableSize`
+without copying canonical text into analysis tables. A no-op sync stays fresh.
+A failed rebuild leaves the stale result intact, while a successful rebuild
+atomically replaces it. Analysis is never scheduled automatically. If the worker
+is absent or fails, `memory_search` and `memory_get` continue to work.
+
+Session transcripts are intentionally out of scope for this first version. Existing
+`unblock-qmd` indexes are derived caches and may be left in place; Unblock Memory
+rebuilds its new index from the configured workspace Markdown.

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+declare const _default: Omit<{
+    id: string;
+    name: string;
+    description: string;
+    kind?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["kind"];
+    configSchema?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema | (() => import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema);
+    reload?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["reload"];
+    nodeHostCommands?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["nodeHostCommands"];
+    securityAuditCollectors?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["securityAuditCollectors"];
+    register: NonNullable<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["register"]>;
+}, "configSchema"> & {
+    configSchema: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,9 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { registerUnblockMemory } from "./src/plugin.js";
+export default definePluginEntry({
+    id: "unblock-memory",
+    name: "Unblock Memory",
+    description: "Workspace-native memory search powered by QMD",
+    kind: "memory",
+    register: registerUnblockMemory,
+});

package/dist/src/analysis.d.ts

@@ -0,0 +1,93 @@
+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?: {
+        method?: "umap" | "none";
+        nComponents?: number;
+        nNeighbors?: number;
+        minDist?: number;
+    };
+    hdbscan?: {
+        minClusterSize?: number;
+        minSamples?: number;
+        clusterSelectionMethod?: "eom" | "leaf";
+        clusterSelectionEpsilon?: number;
+        allowSingleCluster?: boolean;
+    };
+    seed?: number;
+};
+export type AnalysisRunner = (params: {
+    executable: string;
+    dbPath: string;
+    options?: MemoryReclusterOptions;
+    signal?: AbortSignal;
+}) => Promise<void>;
+export type MemoryAnalysisMember = {
+    hash: string;
+    seq: number;
+    probability: number;
+    outlierScore: number;
+    x: number;
+    y: number;
+    representativeRank: number | null;
+    text: string;
+    sourcePaths: string[];
+};
+export type MemoryAnalysisSummary = {
+    status: "ok";
+    runId: string;
+    createdAt: string;
+    completedAt: string;
+    inputDigest: string;
+    model: string;
+    embeddingFingerprint: string;
+    dimensions: number;
+    clusters: number;
+    members: number;
+    noise: number;
+    stale: boolean;
+    staleSince: string | null;
+};
+export type MemoryClusterSummary = {
+    clusterId: string;
+    size: number;
+    availableSize: number;
+    meanProbability: number;
+    preview?: Pick<MemoryAnalysisMember, "hash" | "seq" | "probability" | "text" | "sourcePaths">;
+};
+type AnalysisReadMetadata = {
+    stale: boolean;
+    staleSince: string | null;
+    analyzedAt: string | null;
+    hint?: string;
+};
+export type MemoryClusterList = AnalysisReadMetadata & {
+    status: "ok" | "not_analyzed";
+    runId?: string;
+    clusters: MemoryClusterSummary[];
+    noise: MemoryClusterSummary | null;
+};
+export type MemoryClusterDetail = AnalysisReadMetadata & {
+    status: "ok" | "not_found" | "not_analyzed";
+    runId?: string;
+    cluster?: Omit<MemoryClusterSummary, "preview">;
+    members?: MemoryAnalysisMember[];
+};
+export declare function ensureMemoryAnalysisSchema(db: AnalysisDatabase): void;
+export declare function markMemoryAnalysisStale(db: AnalysisDatabase): void;
+export declare function clusterReference(runId: string, clusterId: number): string;
+export declare function runAnalysisWorker(params: {
+    executable: string;
+    dbPath: string;
+    options?: MemoryReclusterOptions;
+    signal?: AbortSignal;
+}): Promise<void>;
+export declare function latestAnalysisRunId(db: AnalysisDatabase): string | undefined;
+export declare function readAnalysisSummary(db: AnalysisDatabase): MemoryAnalysisSummary | undefined;
+export declare function readClusters(db: AnalysisDatabase, requestedLimit?: number): MemoryClusterList;
+export declare function readCluster(db: AnalysisDatabase, clusterReferenceId: string, requestedLimit?: number): MemoryClusterDetail;
+export {};

package/dist/src/analysis.js

@@ -0,0 +1,406 @@
+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 MAX_EXCERPT_BYTES = 2_000;
+const MAX_TOTAL_EXCERPT_BYTES = 12_000;
+const MAX_ALIASES_PER_MEMBER = 5;
+const MAX_TOTAL_ALIASES = 50;
+export function ensureMemoryAnalysisSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS memory_analysis_runs (
+      id TEXT PRIMARY KEY,
+      created_at TEXT NOT NULL,
+      completed_at TEXT,
+      input_digest TEXT NOT NULL,
+      model TEXT NOT NULL,
+      embedding_fingerprint TEXT NOT NULL,
+      dimensions INTEGER NOT NULL,
+      params_json TEXT NOT NULL,
+      stale_at TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS memory_analysis_clusters (
+      run_id TEXT NOT NULL,
+      cluster_id INTEGER NOT NULL,
+      size INTEGER NOT NULL,
+      mean_probability REAL NOT NULL,
+      PRIMARY KEY (run_id, cluster_id),
+      FOREIGN KEY (run_id) REFERENCES memory_analysis_runs(id) ON DELETE CASCADE
+    );
+
+    CREATE TABLE IF NOT EXISTS memory_analysis_memberships (
+      run_id TEXT NOT NULL,
+      hash TEXT NOT NULL,
+      seq INTEGER NOT NULL,
+      cluster_id INTEGER NOT NULL,
+      probability REAL NOT NULL,
+      outlier_score REAL NOT NULL,
+      x REAL NOT NULL,
+      y REAL NOT NULL,
+      representative_rank INTEGER,
+      PRIMARY KEY (run_id, hash, seq),
+      FOREIGN KEY (run_id) REFERENCES memory_analysis_runs(id) ON DELETE CASCADE
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_memory_analysis_memberships_cluster
+      ON memory_analysis_memberships(run_id, cluster_id, representative_rank);
+  `);
+}
+export function markMemoryAnalysisStale(db) {
+    db.prepare(`
+    UPDATE memory_analysis_runs
+    SET stale_at = COALESCE(stale_at, CURRENT_TIMESTAMP)
+    WHERE id = (
+      SELECT id
+      FROM memory_analysis_runs
+      WHERE completed_at IS NOT NULL
+      ORDER BY completed_at DESC, created_at DESC, id DESC
+      LIMIT 1
+    )
+  `).run();
+}
+export function clusterReference(runId, clusterId) {
+    return createHash("sha256").update(`${runId}\0${clusterId}`).digest("hex").slice(0, 10);
+}
+export function runAnalysisWorker(params) {
+    return new Promise((resolve, reject) => {
+        params.signal?.throwIfAborted();
+        const args = ["--db", params.dbPath];
+        if (params.options && Object.keys(params.options).length > 0) {
+            args.push("--config-json", JSON.stringify(params.options));
+        }
+        const child = spawn(params.executable, args, {
+            shell: false,
+            stdio: ["ignore", "ignore", "pipe"],
+        });
+        const stderr = [];
+        let stderrBytes = 0;
+        const maxErrorBytes = 16_384;
+        child.stderr.on("data", (chunk) => {
+            if (stderrBytes >= maxErrorBytes)
+                return;
+            const remaining = maxErrorBytes - stderrBytes;
+            stderr.push(chunk.subarray(0, remaining));
+            stderrBytes += Math.min(chunk.length, remaining);
+        });
+        let settled = false;
+        let abortError;
+        const cleanup = () => params.signal?.removeEventListener("abort", onAbort);
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            error ? reject(error) : resolve();
+        };
+        const onAbort = () => {
+            if (abortError)
+                return;
+            abortError = params.signal?.reason instanceof Error
+                ? params.signal.reason
+                : new Error("Memory reclustering aborted");
+            child.kill("SIGTERM");
+        };
+        params.signal?.addEventListener("abort", onAbort, { once: true });
+        if (params.signal?.aborted)
+            onAbort();
+        child.on("error", (error) => finish(abortError ?? error));
+        child.on("close", (code, signal) => {
+            if (abortError) {
+                finish(abortError);
+                return;
+            }
+            if (code === 0) {
+                finish();
+                return;
+            }
+            const detail = Buffer.concat(stderr).toString("utf8").trim();
+            finish(new Error(`Memory analysis worker ${signal ? `was terminated by ${signal}` : `exited with code ${code ?? "unknown"}`}${detail ? `: ${detail}` : ""}`));
+        });
+    });
+}
+function latestRun(db) {
+    return db.prepare(`
+    SELECT id, created_at, completed_at, input_digest, model, embedding_fingerprint, dimensions, stale_at
+    FROM memory_analysis_runs
+    WHERE completed_at IS NOT NULL
+    ORDER BY completed_at DESC, created_at DESC, id DESC
+    LIMIT 1
+  `).get();
+}
+export function latestAnalysisRunId(db) {
+    return latestRun(db)?.id;
+}
+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;
+    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);
+    const nonNoise = count(db, "SELECT COUNT(*) AS count FROM memory_analysis_memberships WHERE run_id = ? AND cluster_id <> -1", run.id);
+    const noise = count(db, "SELECT COUNT(*) AS count FROM memory_analysis_memberships WHERE run_id = ? AND cluster_id = -1", run.id);
+    const unassigned = count(db, `
+    SELECT COUNT(*) AS count
+    FROM memory_analysis_memberships m
+    LEFT JOIN memory_analysis_clusters c
+      ON c.run_id = m.run_id AND c.cluster_id = m.cluster_id
+    WHERE m.run_id = ? AND m.cluster_id <> -1 AND c.cluster_id IS NULL
+  `, run.id);
+    if (nonNoise !== expectedNonNoise || members !== nonNoise + noise || unassigned > 0)
+        return undefined;
+    return {
+        status: "ok",
+        runId: run.id,
+        createdAt: run.created_at,
+        completedAt: run.completed_at,
+        inputDigest: run.input_digest,
+        model: run.model,
+        embeddingFingerprint: run.embedding_fingerprint,
+        dimensions: run.dimensions,
+        clusters,
+        members,
+        noise,
+        stale: run.stale_at !== null,
+        staleSince: run.stale_at,
+    };
+}
+function sourcePaths(db, hash, limit) {
+    if (limit <= 0)
+        return [];
+    return db.prepare(`
+    SELECT collection, path
+    FROM documents
+    WHERE hash = ? AND active = 1
+    ORDER BY collection, path
+    LIMIT ?
+  `).all(hash, limit).map((row) => `qmd://${row.collection}/${row.path}`);
+}
+function byteSlice(text, maxBytes) {
+    const bytes = Buffer.from(text);
+    if (bytes.length <= maxBytes)
+        return text;
+    if (maxBytes <= 3)
+        return "";
+    return bytes.subarray(0, maxBytes - 3).toString("utf8").replace(/\uFFFD$/u, "") + "…";
+}
+function members(db, runId, clusterId, limit, maxExcerptBytes = MAX_EXCERPT_BYTES, maxTotalBytes = MAX_TOTAL_EXCERPT_BYTES, maxTotalAliases = MAX_TOTAL_ALIASES) {
+    const noiseOrder = clusterId === -1
+        ? "m.outlier_score DESC, m.hash, m.seq"
+        : `CASE WHEN m.representative_rank IS NULL THEN 1 ELSE 0 END,
+       m.representative_rank,
+       m.probability DESC,
+       m.outlier_score,
+       m.hash,
+       m.seq`;
+    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
+    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);
+    let remaining = maxTotalBytes;
+    let remainingAliases = maxTotalAliases;
+    return rows.map((row) => {
+        const text = remaining <= 0
+            ? ""
+            : byteSlice(row.doc.slice(row.pos, row.pos + row.chunk_len), Math.min(maxExcerptBytes, remaining));
+        remaining -= Buffer.byteLength(text);
+        const aliases = sourcePaths(db, row.hash, Math.min(MAX_ALIASES_PER_MEMBER, remainingAliases));
+        remainingAliases -= aliases.length;
+        return {
+            hash: row.hash,
+            seq: row.seq,
+            probability: row.probability,
+            outlierScore: row.outlier_score,
+            x: row.x,
+            y: row.y,
+            representativeRank: row.representative_rank,
+            text,
+            sourcePaths: aliases,
+        };
+    });
+}
+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
+      )
+  `).get(runId, clusterId)?.count ?? 0;
+}
+function readMetadata(run) {
+    if (!run) {
+        return {
+            stale: true,
+            staleSince: null,
+            analyzedAt: null,
+            hint: "No memory analysis exists. Call memory_recluster, then memory_list_clusters.",
+        };
+    }
+    if (run.stale_at) {
+        return {
+            stale: true,
+            staleSince: run.stale_at,
+            analyzedAt: run.completed_at,
+            hint: "Memory changed after this analysis. Call memory_recluster to refresh it.",
+        };
+    }
+    return { stale: false, staleSince: null, analyzedAt: run.completed_at };
+}
+function toSummary(db, run, row, includePreview, previewBytes = 600, aliasLimit = MAX_TOTAL_ALIASES) {
+    const preview = includePreview
+        ? members(db, run.id, row.cluster_id, 1, previewBytes, previewBytes, aliasLimit)[0]
+        : undefined;
+    return {
+        clusterId: clusterReference(run.id, row.cluster_id),
+        size: row.size,
+        availableSize: row.available_size,
+        meanProbability: row.mean_probability,
+        ...(preview ? {
+            preview: {
+                hash: preview.hash,
+                seq: preview.seq,
+                probability: preview.probability,
+                text: preview.text,
+                sourcePaths: preview.sourcePaths,
+            },
+        } : {}),
+    };
+}
+function noiseRow(db, runId) {
+    return db.prepare(`
+    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,
+      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);
+}
+export function readClusters(db, requestedLimit = DEFAULT_CLUSTER_LIMIT) {
+    const run = latestRun(db);
+    if (!run || !readAnalysisSummary(db)) {
+        return { status: "not_analyzed", ...readMetadata(), clusters: [], noise: null };
+    }
+    const limit = Math.max(1, Math.min(MAX_CLUSTER_LIMIT, Math.floor(requestedLimit)));
+    const rows = db.prepare(`
+    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,
+      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);
+    let remainingBytes = MAX_TOTAL_EXCERPT_BYTES;
+    let remainingAliases = MAX_TOTAL_ALIASES;
+    const clusters = rows.map((row) => {
+        const previewBytes = Math.min(600, remainingBytes);
+        const summary = toSummary(db, run, row, previewBytes > 0, previewBytes, remainingAliases);
+        remainingBytes -= Buffer.byteLength(summary.preview?.text ?? "");
+        remainingAliases -= summary.preview?.sourcePaths.length ?? 0;
+        return summary;
+    });
+    const noise = noiseRow(db, run.id);
+    return {
+        status: "ok",
+        runId: run.id,
+        ...readMetadata(run),
+        clusters,
+        noise: noise ? toSummary(db, run, noise, false) : null,
+    };
+}
+function resolveClusterId(db, runId, reference) {
+    const clusterIds = db.prepare(`
+    SELECT cluster_id
+    FROM memory_analysis_clusters
+    WHERE run_id = ?
+    UNION ALL
+    SELECT -1
+    WHERE EXISTS (
+      SELECT 1 FROM memory_analysis_memberships WHERE run_id = ? AND cluster_id = -1
+    )
+  `).all(runId, runId);
+    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)) {
+        return { status: "not_analyzed", ...readMetadata() };
+    }
+    const metadata = readMetadata(run);
+    const clusterId = resolveClusterId(db, run.id, clusterReferenceId);
+    if (clusterId === undefined) {
+        return {
+            status: "not_found",
+            runId: run.id,
+            ...metadata,
+            hint: "Cluster IDs change after reclustering. Call memory_list_clusters and use a current clusterId.",
+        };
+    }
+    const row = clusterId === -1
+        ? noiseRow(db, run.id)
+        : db.prepare(`
+        SELECT cluster_id, size, mean_probability, 0 AS available_size
+        FROM memory_analysis_clusters
+        WHERE run_id = ? AND cluster_id = ?
+      `).get(run.id, clusterId);
+    if (!row) {
+        return { status: "not_found", runId: run.id, ...metadata };
+    }
+    const limit = Math.max(1, Math.min(MAX_MEMBER_LIMIT, Math.floor(requestedLimit)));
+    return {
+        status: "ok",
+        runId: run.id,
+        ...metadata,
+        cluster: {
+            clusterId: clusterReferenceId,
+            size: row.size,
+            availableSize: availableSize(db, run.id, clusterId),
+            meanProbability: row.mean_probability,
+        },
+        members: members(db, run.id, clusterId, limit),
+    };
+}

package/dist/src/config.d.ts

@@ -0,0 +1,8 @@
+export declare const DEFAULT_PATHS: readonly ["MEMORY.md", "USER.md", "memory/**/*.md"];
+export type UnblockMemoryConfig = {
+    paths: readonly string[];
+    analysis: {
+        executable?: string;
+    };
+};
+export declare function resolveConfig(value: unknown): UnblockMemoryConfig;

package/dist/src/config.js

@@ -0,0 +1,27 @@
+import { isAbsolute } from "node:path";
+export const DEFAULT_PATHS = ["MEMORY.md", "USER.md", "memory/**/*.md"];
+export function resolveConfig(value) {
+    if (!value || typeof value !== "object") {
+        return { paths: DEFAULT_PATHS, analysis: {} };
+    }
+    const config = value;
+    let paths = DEFAULT_PATHS;
+    if (config.paths !== undefined) {
+        if (!Array.isArray(config.paths) || !config.paths.every((entry) => typeof entry === "string" && entry.trim())) {
+            throw new Error("unblock-memory paths must be an array of non-empty strings");
+        }
+        paths = config.paths.map((entry) => entry.trim());
+    }
+    if (config.analysis === undefined)
+        return { paths, analysis: {} };
+    if (!config.analysis || typeof config.analysis !== "object") {
+        throw new Error("unblock-memory analysis must be an object");
+    }
+    const configured = config.analysis.executable;
+    if (configured === undefined)
+        return { paths, analysis: {} };
+    if (typeof configured !== "string" || !configured.trim() || !isAbsolute(configured.trim())) {
+        throw new Error("unblock-memory analysis.executable must be an absolute non-empty path");
+    }
+    return { paths, analysis: { executable: configured.trim() } };
+}