@unblocklabs/unblock-memory 0.1.2 → 0.2.0

package/README.md

@@ -13,7 +13,7 @@ index. It does not re-embed memory, copy vectors, or create another database.
 From npm:
 
 ```bash
-openclaw plugins install @unblocklabs/unblock-memory
+openclaw plugins install npm:@unblocklabs/unblock-memory
 ```
 
 Or directly from GitHub:
@@ -22,10 +22,15 @@ Or directly from GitHub:
 openclaw plugins install git:github.com/unblocklabs-ai/unblock-memory
 ```
 
+Install the plugin once on each OpenClaw host, not once per agent. It installs
+its pinned `@unblocklabs/qmd` runtime dependency automatically, so QMD does not
+need to be installed separately. Each agent gets its own QMD index when it first
+uses memory.
+
 ## Configuration
 
-Select the plugin as the memory provider and list any exact Markdown files,
-directories, or globs to index:
+Select the plugin as the memory provider and group exact Markdown files,
+directories, or globs into named corpora:
 
 ```json5
 {
@@ -34,14 +39,26 @@ directories, or globs to index:
     entries: {
       "unblock-memory": {
         config: {
-          paths: [
-            "MEMORY.md",
-            "USER.md",
-            "memory/**/*.md",
-            "/absolute/shared/**/*.md",
+          corpora: [
+            {
+              name: "memory",
+              kind: "files",
+              paths: ["MEMORY.md", "USER.md", "memory/**/*.md"],
+            },
+            {
+              name: "projects",
+              kind: "files",
+              paths: ["/absolute/shared/**/*.md"],
+            },
+            {
+              name: "sessions",
+              kind: "sessions",
+              chatTypes: ["channel", "group"],
+            },
           ],
+          // Optional: omit unless the local analysis worker is installed.
           analysis: {
-            executable: "/absolute/path/to/unblock-memory-analysis",
+            executable: "/absolute/path/to/unblock-cluster/bin/unblock-memory-analysis",
           },
         },
       },
@@ -51,9 +68,47 @@ directories, or globs to index:
 ```
 
 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.
+paths are supported. A directory means recursive Markdown. When `corpora` is
+omitted, the plugin creates a `memory` corpus containing `MEMORY.md`, `USER.md`,
+and `memory/**/*.md`. Explicit configuration must include exactly one `memory`
+corpus; other unique names may be added for custom material.
+
+`memory_search` searches every configured corpus by default. Pass
+`corpora: ["projects"]` to search selected corpora or `corpora: ["all"]` to
+request all of them explicitly. Search results include their corpus name and
+remain readable by passing the returned `qmd://` path to `memory_get`.
+
+Use `sessionFilter` to restrict session results by metadata while leaving file
+corpora searchable. Supported fields are `startedFrom` and `startedTo`
+(inclusive ISO 8601 timestamps), `provider`, `chatType`, `accountId`, and
+`conversationId`:
+
+```json
+{
+  "query": "deployment decision",
+  "sessionFilter": {
+    "startedFrom": "2026-08-01T00:00:00Z",
+    "provider": "slack",
+    "chatType": "channel"
+  }
+}
+```
+
+Provider matching is case-normalized; `chatType` uses the lowercase values
+shown in the configuration example. Account and conversation IDs are trimmed
+and matched exactly. When only `sessions` is selected and no sessions match,
+search returns no results. With other corpora selected, their results remain
+eligible.
+
+The optional `sessions` corpus reads the current agent's normal OpenClaw SQLite
+store and indexes its active user/assistant transcript branch. It defaults to
+channel and group conversations; add `direct` explicitly to include DMs. Run
+`memory_sync_sessions` to refresh it. Projections are private derived Markdown
+under the agent's `unblock-memory/sessions` state directory and can be rebuilt
+from OpenClaw at any time. Session results include provider, chat type,
+conversation identity, and start time. They participate in the same search and
+clustering index as file memory. This phase does not sync sessions at startup or
+on a schedule; refreshes are manual through `memory_sync_sessions`.
 
 Indexes live at `~/.openclaw/agents/<agentId>/unblock-memory/index.sqlite` (or the
 equivalent configured OpenClaw state directory). The first lookup builds the
@@ -62,12 +117,30 @@ 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,
+Analysis is opt-in. Core indexing, `memory_search`, and `memory_get` need only
+Unblock Memory and its automatically installed QMD dependency. To enable
+clustering, install the
+[`unblock-cluster`](https://github.com/unblocklabs-ai/unblock-cluster) worker once
+on the same host:
+
+```bash
+git clone https://github.com/unblocklabs-ai/unblock-cluster.git
+cd unblock-cluster
+python3 -m venv .venv
+.venv/bin/python -m pip install -r requirements.txt
+```
+
+Set `analysis.executable` to the absolute path of
+`bin/unblock-memory-analysis` in that checkout. One worker installation can
+serve every agent on the host. The plugin invokes it directly with
+`--db <the agent's known index path>` and, when requested, a validated
+`--config-json <clustering options>` payload. Agents cannot choose a database,
 executable, shell command, or arbitrary arguments.
 
+Without the worker, `memory_list_clusters` reports that memory has not been
+analyzed and `memory_recluster` reports that analysis is unavailable. Ordinary
+memory search and reads continue to work.
+
 The analysis worker reads QMD's existing semantic vectors and writes only
 derived results into three namespaced tables in that same `index.sqlite`:
 
@@ -100,6 +173,5 @@ 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.
+Existing `unblock-qmd` indexes are derived caches and may be left in place;
+Unblock Memory rebuilds its own index from configured corpora.

package/dist/src/config.d.ts

@@ -1,8 +1,22 @@
-export declare const DEFAULT_PATHS: readonly ["MEMORY.md", "USER.md", "memory/**/*.md"];
-export type UnblockMemoryConfig = {
+export type FileCorpusConfig = {
+    name: string;
+    kind: "files";
     paths: readonly string[];
+};
+declare const CHAT_TYPES: readonly ["channel", "group", "direct"];
+export type ChatType = typeof CHAT_TYPES[number];
+type SessionCorpusConfig = {
+    name: "sessions";
+    kind: "sessions";
+    chatTypes: readonly ChatType[];
+};
+export type CorpusConfig = FileCorpusConfig | SessionCorpusConfig;
+export declare const DEFAULT_CORPORA: readonly FileCorpusConfig[];
+export type UnblockMemoryConfig = {
+    corpora: readonly CorpusConfig[];
     analysis: {
         executable?: string;
     };
 };
 export declare function resolveConfig(value: unknown): UnblockMemoryConfig;
+export {};

package/dist/src/config.js

@@ -1,27 +1,90 @@
 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 DEFAULT_PATHS = ["MEMORY.md", "USER.md", "memory/**/*.md"];
+const CHAT_TYPES = ["channel", "group", "direct"];
+export const DEFAULT_CORPORA = [{
+        name: "memory",
+        kind: "files",
+        paths: DEFAULT_PATHS,
+    }];
+function assertOnlyKeys(value, allowed, label) {
+    const unknown = Object.keys(value).find((key) => !allowed.includes(key));
+    if (unknown)
+        throw new Error(`unblock-memory ${label} has unknown property: ${unknown}`);
+}
+function resolveCorpora(value) {
+    if (value === undefined)
+        return DEFAULT_CORPORA;
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new Error("unblock-memory corpora must be a non-empty array");
     }
-    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");
+    const names = new Set();
+    const corpora = value.map((entry, index) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            throw new Error(`unblock-memory corpora[${index}] must be an object`);
+        }
+        const corpus = entry;
+        if (typeof corpus.name !== "string" || !corpus.name.trim()) {
+            throw new Error(`unblock-memory corpora[${index}].name must be a non-empty string`);
+        }
+        const name = corpus.name.trim();
+        if (name === "all") {
+            throw new Error(`unblock-memory corpus name is reserved: ${name}`);
+        }
+        if (names.has(name))
+            throw new Error(`unblock-memory corpus names must be unique: ${name}`);
+        names.add(name);
+        if (corpus.kind === "sessions") {
+            assertOnlyKeys(corpus, ["name", "kind", "chatTypes"], `corpora[${index}]`);
+            if (name !== "sessions") {
+                throw new Error('unblock-memory session corpus must be named "sessions"');
+            }
+            const chatTypes = corpus.chatTypes ?? ["channel", "group"];
+            if (!Array.isArray(chatTypes) || chatTypes.length === 0 ||
+                !chatTypes.every((chatType) => CHAT_TYPES.includes(chatType))) {
+                throw new Error(`unblock-memory corpus sessions chatTypes must contain channel, group, or direct`);
+            }
+            return { name: "sessions", kind: "sessions", chatTypes: [...new Set(chatTypes)] };
+        }
+        assertOnlyKeys(corpus, ["name", "kind", "paths"], `corpora[${index}]`);
+        if (name === "sessions") {
+            throw new Error('unblock-memory corpus named "sessions" must have kind "sessions"');
         }
-        paths = config.paths.map((entry) => entry.trim());
+        if (corpus.kind !== "files") {
+            throw new Error(`unblock-memory corpus ${name} must have kind "files" or "sessions"`);
+        }
+        if (!Array.isArray(corpus.paths) || corpus.paths.length === 0 ||
+            !corpus.paths.every((path) => typeof path === "string" && path.trim())) {
+            throw new Error(`unblock-memory corpus ${name} paths must be a non-empty array of non-empty strings`);
+        }
+        return { name, kind: "files", paths: corpus.paths.map((path) => path.trim()) };
+    });
+    if (corpora.filter((corpus) => corpus.name === "memory").length !== 1) {
+        throw new Error('unblock-memory corpora must contain exactly one corpus named "memory"');
     }
+    return corpora;
+}
+export function resolveConfig(value) {
+    if (value === undefined || value === null) {
+        return { corpora: DEFAULT_CORPORA, analysis: {} };
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("unblock-memory config must be an object");
+    }
+    const config = value;
+    assertOnlyKeys(config, ["corpora", "analysis"], "config");
+    const corpora = resolveCorpora(config.corpora);
     if (config.analysis === undefined)
-        return { paths, analysis: {} };
-    if (!config.analysis || typeof config.analysis !== "object") {
+        return { corpora, analysis: {} };
+    if (!config.analysis || typeof config.analysis !== "object" || Array.isArray(config.analysis)) {
         throw new Error("unblock-memory analysis must be an object");
     }
-    const configured = config.analysis.executable;
+    const analysis = config.analysis;
+    assertOnlyKeys(analysis, ["executable"], "analysis");
+    const configured = analysis.executable;
     if (configured === undefined)
-        return { paths, analysis: {} };
+        return { corpora, 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() } };
+    return { corpora, analysis: { executable: configured.trim() } };
 }

package/dist/src/contracts.d.ts

@@ -1,9 +1,27 @@
 import type { MemoryPluginCapability } from "openclaw/plugin-sdk/memory-host-core";
+import type { SessionMetadata } from "./session-projector.js";
+import type { ChatType } from "./config.js";
 export type MemoryPluginRuntimeContract = NonNullable<MemoryPluginCapability["runtime"]>;
 type ManagerLookup = Awaited<ReturnType<MemoryPluginRuntimeContract["getMemorySearchManager"]>>;
 export type MemorySearchManagerContract = NonNullable<ManagerLookup["manager"]>;
 export type MemoryProviderStatus = ReturnType<MemorySearchManagerContract["status"]>;
 export type MemorySearchResult = Awaited<ReturnType<MemorySearchManagerContract["search"]>>[number];
+export type CorpusMemorySearchResult = MemorySearchResult & {
+    corpus: string;
+    session?: SessionMetadata;
+};
+export type SessionSearchFilter = {
+    startedFrom?: string;
+    startedTo?: string;
+    provider?: string;
+    chatType?: ChatType;
+    accountId?: string;
+    conversationId?: string;
+};
+export type CorpusSearchOptions = NonNullable<Parameters<MemorySearchManagerContract["search"]>[1]> & {
+    corpora?: readonly string[];
+    sessionFilter?: SessionSearchFilter;
+};
 export type MemoryEmbeddingProbeResult = Awaited<ReturnType<MemorySearchManagerContract["probeEmbeddingAvailability"]>>;
 export type MemorySyncParams = Parameters<NonNullable<MemorySearchManagerContract["sync"]>>[0];
 export type MemoryReadResult = {

package/dist/src/manager.d.ts

@@ -1,8 +1,20 @@
 import type { QMDStore } from "@unblocklabs/qmd";
 import { type AnalysisRunner, type MemoryAnalysisSummary, type MemoryClusterDetail, type MemoryClusterList, type MemoryReclusterOptions } from "./analysis.js";
-import type { MemoryEmbeddingProbeResult, MemoryProviderStatus, MemoryReadResult, MemorySearchManagerContract, MemorySearchResult, MemorySyncParams } from "./contracts.js";
+import type { CorpusMemorySearchResult, CorpusSearchOptions, MemoryEmbeddingProbeResult, MemoryProviderStatus, MemoryReadResult, MemorySearchManagerContract, MemorySyncParams } from "./contracts.js";
+import type { ChatType } from "./config.js";
+import { type SessionSyncResult } from "./session-sync.js";
 import { type ResolvedSource } from "./sources.js";
 export type ManagerStore = Pick<QMDStore, "update" | "embed" | "getStatus" | "listCollections" | "searchLex" | "vsearch" | "get" | "getDocumentBody" | "close">;
+export type ManagerSessionConfig = {
+    agentId: string;
+    agentName: string;
+    chatTypes: readonly ChatType[];
+    collection: string;
+    databasePath: string;
+    manifestPath: string;
+    outputDir: string;
+    timezone: string;
+};
 export declare function enableSecureDelete(store: QMDStore): void;
 export declare function cleanupRemovedDocuments(store: QMDStore, changedDocuments?: number): number;
 export declare function pruneStaleCollections(store: QMDStore, configuredCollections: ReadonlySet<string>): Promise<number>;
@@ -21,22 +33,18 @@ export declare class QmdMemoryManager implements MemorySearchManagerContract {
         storeFactory?: () => Promise<ManagerStore>;
         analysisExecutable?: string;
         analysisRunner?: AnalysisRunner;
+        sessions?: ManagerSessionConfig;
     });
     start(): Promise<void>;
     sync(params?: MemorySyncParams): Promise<void>;
+    syncSessions(force?: boolean): Promise<SessionSyncResult>;
     recluster(options?: MemoryReclusterOptions, signal?: AbortSignal): Promise<MemoryAnalysisSummary>;
     listClusters(limit?: number): Promise<MemoryClusterList>;
     fetchCluster(params: {
         clusterId: string;
         topK?: number;
     }): Promise<MemoryClusterDetail>;
-    search(query: string, opts?: {
-        maxResults?: number;
-        minScore?: number;
-        lexicalOnly?: boolean;
-        sources?: Array<"memory" | "sessions">;
-        signal?: AbortSignal;
-    }): Promise<MemorySearchResult[]>;
+    search(query: string, opts?: CorpusSearchOptions): Promise<CorpusMemorySearchResult[]>;
     readFile(params: {
         relPath: string;
         from?: number;