@unblocklabs/unblock-memory 0.1.2 → 0.2.1

package/dist/src/session-projector.js

@@ -0,0 +1,163 @@
+import { createHash } from "node:crypto";
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function timestamp(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value !== "string")
+        return undefined;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function textContent(value) {
+    if (typeof value === "string")
+        return value.trim() || undefined;
+    if (!Array.isArray(value))
+        return undefined;
+    const text = value.flatMap((item) => {
+        const block = record(item);
+        if (!block || typeof block.type !== "string")
+            throw new Error("invalid transcript content block");
+        if (!["text", "toolCall", "toolResult", "thinking", "image"].includes(block.type)) {
+            throw new Error(`unsupported transcript content block: ${block.type}`);
+        }
+        if (block.type === "text" && typeof block.text !== "string") {
+            throw new Error("invalid transcript text block");
+        }
+        return block?.type === "text" && typeof block.text === "string" ? [block.text] : [];
+    }).join("\n").trim();
+    return text || undefined;
+}
+function projectMessage(row, input) {
+    let event;
+    try {
+        event = JSON.parse(row.eventJson);
+    }
+    catch {
+        throw new Error("invalid transcript event JSON");
+    }
+    const eventRecord = record(event);
+    if (eventRecord?.type !== "message")
+        return undefined;
+    const message = record(eventRecord?.message);
+    if (!message)
+        throw new Error("invalid transcript message event");
+    const role = message.role;
+    if (role !== "user" && role !== "assistant")
+        return undefined;
+    if (typeof message.content !== "string" && !Array.isArray(message.content)) {
+        throw new Error("invalid transcript message content");
+    }
+    let text = textContent(message.content);
+    if (!text)
+        return undefined;
+    if (text === "HEARTBEAT_OK")
+        return undefined;
+    if (role === "user" && (text === "[OpenClaw heartbeat poll]" ||
+        text.startsWith("[Subagent Context]") ||
+        text.startsWith("<relevant-memories>")))
+        return undefined;
+    const metadata = record(message.__openclaw);
+    const speaker = role === "assistant"
+        ? input.agentName
+        : nonEmptyString(metadata?.senderName) ??
+            nonEmptyString(metadata?.senderUsername) ??
+            nonEmptyString(metadata?.senderId) ??
+            nonEmptyString(message.senderName) ??
+            nonEmptyString(message.senderLabel) ??
+            nonEmptyString(message.senderId) ??
+            "User";
+    if (role === "user" && speaker !== "User") {
+        text = text.replace(/^From:[^\n]*\n/u, "").trim();
+    }
+    if (!text)
+        return undefined;
+    return {
+        speaker: speaker.replace(/[\r\n]+/gu, " "),
+        text,
+        timestamp: timestamp(eventRecord.timestamp) ?? row.createdAt ?? timestamp(message.timestamp) ?? input.startedAt,
+    };
+}
+function formatTimestamp(value, timezone) {
+    const parts = new Intl.DateTimeFormat("en-CA", {
+        timeZone: timezone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+        hourCycle: "h23",
+        timeZoneName: "short",
+    }).formatToParts(value);
+    const part = (type) => parts.find((entry) => entry.type === type)?.value ?? "";
+    return `${part("year")}-${part("month")}-${part("day")} ` +
+        `${part("hour")}:${part("minute")}:${part("second")} ${part("timeZoneName")}`.trim();
+}
+function inline(value) {
+    return value.replace(/[\r\n]+/gu, " ").replaceAll("`", "\\`");
+}
+export function projectSession(input) {
+    const messages = input.events.flatMap((event) => {
+        const projected = projectMessage(event, input);
+        return projected ? [projected] : [];
+    });
+    if (messages.length === 0)
+        return undefined;
+    const provider = input.provider ?? "unknown";
+    const header = [
+        "# Session",
+        "",
+        `- Session ID: \`${inline(input.sessionId)}\``,
+        `- Provider: ${inline(provider)}`,
+        `- Chat type: ${input.chatType}`,
+        ...(input.label ? [`- Conversation: ${inline(input.label)}`] : []),
+        ...(input.conversationId ? [`- Conversation ID: \`${inline(input.conversationId)}\``] : []),
+        `- Started: ${new Date(input.startedAt).toISOString()}`,
+        "",
+        "## Transcript",
+        "",
+    ];
+    const transcript = messages.map((message) => `${formatTimestamp(message.timestamp, input.timezone)} — ${message.speaker}: ${message.text}`);
+    return `${[...header, ...transcript].join("\n\n")}\n`;
+}
+function hash(value) {
+    return createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+function pathComponent(value, fallback, privateId = false) {
+    const normalized = value?.trim();
+    if (!normalized)
+        return fallback;
+    if (privateId || normalized.includes("@") || /^\+?\d{6,}$/u.test(normalized)) {
+        return `id-${hash(normalized)}`;
+    }
+    const safe = normalized.replace(/[^a-zA-Z0-9._-]+/gu, "-").replace(/^-+|-+$/gu, "");
+    return safe && safe !== "." && safe !== ".." ? safe.slice(0, 80) : `id-${hash(normalized)}`;
+}
+export function sessionDocumentPath(metadata) {
+    const provider = pathComponent(metadata.provider?.toLowerCase(), "unknown");
+    const privateConversation = provider === "imessage";
+    const account = pathComponent(metadata.accountId, "default", privateConversation);
+    const conversation = pathComponent(metadata.conversationId, `session-${hash(metadata.sessionId)}`, privateConversation);
+    const started = new Date(metadata.startedAt).toISOString().replaceAll(":", "-").replace(/\.\d{3}Z$/u, "Z");
+    const sessionId = pathComponent(metadata.sessionId, hash(metadata.sessionId));
+    return `${provider}/${metadata.chatType}/${account}/${conversation}/${started}--${sessionId}.md`;
+}
+export function resolveTimezone(configured) {
+    if (configured) {
+        try {
+            new Intl.DateTimeFormat("en-US", { timeZone: configured }).format();
+            return configured;
+        }
+        catch {
+            // OpenClaw normally validates this; use the host timezone for stale config.
+        }
+    }
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+}

package/dist/src/session-sync.d.ts

@@ -0,0 +1,43 @@
+import type { ChatType } from "./config.js";
+import { type SessionMetadata } from "./session-projector.js";
+type IndexedSession = SessionMetadata & {
+    sourceGeneration: string;
+    maxSeq: number;
+    activeEventCount: number;
+    sizeBytes: number;
+    projectionHash: string;
+    documentPath: string;
+    projectorVersion: number;
+};
+export type SessionManifest = {
+    version: number;
+    lastSuccessfulSyncAt?: number;
+    sessions: Record<string, IndexedSession>;
+};
+export type SessionSyncResult = {
+    scanned: number;
+    unchanged: number;
+    updated: number;
+    removed: number;
+    skipped: number;
+    failed: number;
+    embedded: number;
+    lastSuccessfulSyncAt: number;
+};
+export declare function readSessionManifest(path: string): Promise<SessionManifest>;
+export declare function sessionMetadataByPath(manifest: SessionManifest): Map<string, SessionMetadata>;
+export declare function syncSessionProjections(params: {
+    databasePath: string;
+    outputDir: string;
+    manifestPath: string;
+    agentId: string;
+    agentName: string;
+    timezone: string;
+    chatTypes: readonly ChatType[];
+    force?: boolean;
+    index?: () => Promise<number>;
+}): Promise<{
+    result: SessionSyncResult;
+    manifest: SessionManifest;
+}>;
+export {};

package/dist/src/session-sync.js

@@ -0,0 +1,302 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, lstatSync } from "node:fs";
+import { chmod, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { projectSession, sessionDocumentPath, } from "./session-projector.js";
+const MANIFEST_VERSION = 1;
+const PROJECTOR_VERSION = 1;
+const SUPPORTED_SCHEMA_VERSION = 17;
+const REQUIRED_COLUMNS = {
+    schema_meta: ["meta_key", "role", "schema_version", "agent_id", "app_version"],
+    session_windows: [
+        "session_id", "session_key", "chat_type", "channel", "account_id",
+        "primary_conversation_id", "created_at", "started_at", "ended_at",
+    ],
+    conversations: [
+        "conversation_id", "channel", "account_id", "kind", "peer_id",
+        "thread_id", "native_channel_id", "native_direct_user_id", "label",
+    ],
+    transcript_events: ["session_id", "seq", "event_json", "created_at"],
+    session_transcript_active_events: ["session_id", "active_position", "event_seq", "message_position"],
+    transcript_rewrite_watermarks: ["session_id", "generation"],
+};
+function projectionPath(outputDir, documentPath) {
+    const root = resolve(outputDir);
+    const target = resolve(root, documentPath);
+    const pathFromRoot = relative(root, target);
+    if (!pathFromRoot || pathFromRoot === ".." || pathFromRoot.startsWith(`..${sep}`) || isAbsolute(pathFromRoot)) {
+        throw new Error(`invalid unblock-memory session document path: ${documentPath}`);
+    }
+    let current = root;
+    for (const component of ["", ...pathFromRoot.split(sep)]) {
+        current = component ? join(current, component) : current;
+        try {
+            if (lstatSync(current).isSymbolicLink()) {
+                throw new Error(`invalid unblock-memory session document path: ${documentPath}`);
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    return target;
+}
+function assertSchema(db, expectedAgentId) {
+    const pragma = db.prepare("PRAGMA user_version").get();
+    if (pragma?.user_version !== SUPPORTED_SCHEMA_VERSION) {
+        throw new Error(`unsupported OpenClaw agent database schema: expected ${SUPPORTED_SCHEMA_VERSION}, ` +
+            `found ${String(pragma?.user_version ?? "unknown")}`);
+    }
+    for (const [table, required] of Object.entries(REQUIRED_COLUMNS)) {
+        const columns = new Set(db.prepare(`PRAGMA table_info(${table})`).all()
+            .map((column) => column.name));
+        const missing = required.find((column) => !columns.has(column));
+        if (missing)
+            throw new Error(`unsupported OpenClaw agent database: missing ${table}.${missing}`);
+    }
+    const meta = db.prepare("SELECT role, schema_version AS schemaVersion, agent_id AS agentId " +
+        "FROM schema_meta WHERE meta_key = 'primary' LIMIT 1").get();
+    if (meta?.role !== "agent" || meta.schemaVersion !== SUPPORTED_SCHEMA_VERSION) {
+        throw new Error("unsupported OpenClaw agent database primary schema metadata");
+    }
+    if (meta.agentId !== expectedAgentId) {
+        throw new Error(`OpenClaw agent database belongs to ${String(meta.agentId)}, not ${expectedAgentId}`);
+    }
+}
+function readSnapshot(params) {
+    const db = new DatabaseSync(params.databasePath, { readOnly: true });
+    try {
+        db.exec("PRAGMA query_only = ON; PRAGMA busy_timeout = 5000; BEGIN");
+        assertSchema(db, params.agentId);
+        const placeholders = params.chatTypes.map(() => "?").join(", ");
+        const windows = db.prepare(`
+      SELECT
+        window.session_id AS sessionId,
+        window.chat_type AS chatType,
+        COALESCE(window.channel, conversation.channel) AS provider,
+        COALESCE(window.account_id, conversation.account_id) AS accountId,
+        COALESCE(conversation.native_channel_id, conversation.native_direct_user_id,
+                 conversation.peer_id, window.primary_conversation_id) AS conversationId,
+        conversation.label AS label,
+        COALESCE(window.started_at, window.created_at) AS startedAt,
+        rewrite.generation AS sourceGeneration,
+        MAX(active.event_seq) AS maxSeq,
+        COUNT(active.event_seq) AS activeEventCount
+      FROM session_windows AS window
+      LEFT JOIN conversations AS conversation
+        ON conversation.conversation_id = window.primary_conversation_id
+      LEFT JOIN transcript_rewrite_watermarks AS rewrite
+        ON rewrite.session_id = window.session_id
+      LEFT JOIN session_transcript_active_events AS active
+        ON active.session_id = window.session_id
+      WHERE window.chat_type IN (${placeholders})
+      GROUP BY window.session_id
+      ORDER BY window.created_at, window.session_id
+    `).all(...params.chatTypes);
+        const readEvents = db.prepare(`
+      SELECT active.session_id AS sessionId, event.event_json AS eventJson,
+             event.created_at AS createdAt
+      FROM session_transcript_active_events AS active
+      JOIN transcript_events AS event
+        ON event.session_id = active.session_id AND event.seq = active.event_seq
+      WHERE active.session_id = ?
+      ORDER BY active.active_position
+    `);
+        const events = new Map();
+        for (const window of windows) {
+            const metadata = {
+                sessionId: window.sessionId,
+                provider: window.provider ?? undefined,
+                chatType: window.chatType,
+                accountId: window.accountId ?? undefined,
+                conversationId: window.conversationId ?? undefined,
+                startedAt: window.startedAt,
+            };
+            const previous = params.previousManifest.sessions[window.sessionId];
+            const documentPath = sessionDocumentPath(metadata);
+            const unchanged = !params.force &&
+                previous?.sourceGeneration === window.sourceGeneration &&
+                previous.maxSeq === (window.maxSeq ?? 0) &&
+                previous.projectorVersion === PROJECTOR_VERSION &&
+                previous.documentPath === documentPath &&
+                existsSync(projectionPath(params.outputDir, documentPath));
+            if (!unchanged) {
+                events.set(window.sessionId, readEvents.all(window.sessionId));
+            }
+        }
+        db.exec("COMMIT");
+        return { windows, events };
+    }
+    catch (error) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch { /* transaction may not have started */ }
+        throw error;
+    }
+    finally {
+        db.close();
+    }
+}
+function emptyManifest() {
+    return { version: MANIFEST_VERSION, sessions: {} };
+}
+export async function readSessionManifest(path) {
+    if (!existsSync(path))
+        return emptyManifest();
+    let value;
+    try {
+        value = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        throw new Error(`invalid unblock-memory session manifest: ${path}`);
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`invalid unblock-memory session manifest: ${path}`);
+    }
+    const manifest = value;
+    if (manifest.version !== MANIFEST_VERSION || !manifest.sessions ||
+        typeof manifest.sessions !== "object" || Array.isArray(manifest.sessions)) {
+        throw new Error(`unsupported unblock-memory session manifest: ${path}`);
+    }
+    return manifest;
+}
+async function atomicWrite(path, content, mode) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, content, { encoding: "utf8", mode });
+        await rename(temporary, path);
+        await chmod(path, mode);
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+}
+async function remove(path) {
+    try {
+        await unlink(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function projectionHash(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+export function sessionMetadataByPath(manifest) {
+    return new Map(Object.values(manifest.sessions).map((session) => [session.documentPath, {
+            sessionId: session.sessionId,
+            provider: session.provider,
+            chatType: session.chatType,
+            accountId: session.accountId,
+            conversationId: session.conversationId,
+            startedAt: session.startedAt,
+        }]));
+}
+export async function syncSessionProjections(params) {
+    const previousManifest = await readSessionManifest(params.manifestPath);
+    const snapshot = readSnapshot({
+        ...params,
+        force: params.force === true,
+        previousManifest,
+    });
+    const sessions = {};
+    const counts = { unchanged: 0, updated: 0, removed: 0, skipped: 0, failed: 0 };
+    await mkdir(params.outputDir, { recursive: true, mode: 0o700 });
+    await chmod(params.outputDir, 0o700);
+    for (const window of snapshot.windows) {
+        const previous = previousManifest.sessions[window.sessionId];
+        const events = snapshot.events.get(window.sessionId);
+        const metadata = {
+            sessionId: window.sessionId,
+            provider: window.provider ?? undefined,
+            chatType: window.chatType,
+            accountId: window.accountId ?? undefined,
+            conversationId: window.conversationId ?? undefined,
+            startedAt: window.startedAt,
+        };
+        const documentPath = sessionDocumentPath(metadata);
+        if (events === undefined) {
+            sessions[window.sessionId] = previous;
+            counts.unchanged += 1;
+            continue;
+        }
+        if (events.length > 0 && (!window.sourceGeneration || window.maxSeq === null)) {
+            counts.failed += 1;
+            if (previous)
+                sessions[window.sessionId] = previous;
+            continue;
+        }
+        let content;
+        try {
+            const input = {
+                ...metadata,
+                label: window.label ?? undefined,
+                agentName: params.agentName,
+                timezone: params.timezone,
+                events,
+            };
+            content = projectSession(input);
+        }
+        catch {
+            counts.failed += 1;
+            if (previous)
+                sessions[window.sessionId] = previous;
+            continue;
+        }
+        if (!content) {
+            counts.skipped += 1;
+            if (previous) {
+                await remove(projectionPath(params.outputDir, previous.documentPath));
+                counts.removed += 1;
+            }
+            continue;
+        }
+        const target = projectionPath(params.outputDir, documentPath);
+        await atomicWrite(target, content, 0o600);
+        if (previous?.documentPath && previous.documentPath !== documentPath) {
+            await remove(projectionPath(params.outputDir, previous.documentPath));
+        }
+        sessions[window.sessionId] = {
+            ...metadata,
+            sourceGeneration: window.sourceGeneration,
+            maxSeq: window.maxSeq,
+            activeEventCount: window.activeEventCount,
+            sizeBytes: Buffer.byteLength(content),
+            projectionHash: projectionHash(content),
+            documentPath,
+            projectorVersion: PROJECTOR_VERSION,
+        };
+        counts.updated += 1;
+    }
+    for (const [sessionId, session] of Object.entries(previousManifest.sessions)) {
+        if (sessions[sessionId] || snapshot.windows.some((window) => window.sessionId === sessionId))
+            continue;
+        await remove(projectionPath(params.outputDir, session.documentPath));
+        counts.removed += 1;
+    }
+    const embedded = await params.index?.() ?? 0;
+    const lastSuccessfulSyncAt = Date.now();
+    const manifest = {
+        version: MANIFEST_VERSION,
+        lastSuccessfulSyncAt,
+        sessions,
+    };
+    await atomicWrite(params.manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 0o600);
+    return {
+        result: {
+            scanned: snapshot.windows.length,
+            ...counts,
+            embedded,
+            lastSuccessfulSyncAt,
+        },
+        manifest,
+    };
+}

package/dist/src/sources.d.ts

@@ -1,11 +1,17 @@
+import type { ChatType, FileCorpusConfig } from "./config.js";
 export type ResolvedSource = {
     collection: string;
+    corpus: string;
     configuredPath: string;
+    kind: "files" | "sessions";
     root: string;
     pattern: string;
     watchPath: string;
+    chatTypes?: readonly ChatType[];
 };
-export declare function resolveSource(workspaceDir: string, configuredPath: string): ResolvedSource;
+export declare function resolveSource(workspaceDir: string, configuredPath: string, corpus?: string): ResolvedSource;
+export declare function resolveSessionSource(sessionsDir: string, chatTypes: readonly ChatType[]): ResolvedSource;
+export declare function resolveSources(workspaceDir: string, corpora: readonly FileCorpusConfig[]): ResolvedSource[];
 export declare function parseSafeVirtualPath(virtualPath: string, sources: ReadonlyMap<string, ResolvedSource>): {
     source: ResolvedSource;
     relativePath: string;

package/dist/src/sources.js

@@ -29,7 +29,7 @@ function assertWorkspaceSourceHasNoSymlinkRoot(workspaceDir, configuredPath, roo
         current = parent;
     }
 }
-export function resolveSource(workspaceDir, configuredPath) {
+export function resolveSource(workspaceDir, configuredPath, corpus = "memory") {
     const expanded = expandHome(configuredPath);
     const absolute = isAbsolute(expanded) ? resolve(expanded) : resolve(workspaceDir, expanded);
     if (existsSync(absolute)) {
@@ -39,7 +39,9 @@ export function resolveSource(workspaceDir, configuredPath) {
         assertWorkspaceSourceHasNoSymlinkRoot(workspaceDir, configuredPath, root);
         return {
             collection: collectionName(absolute),
+            corpus,
             configuredPath,
+            kind: "files",
             root,
             pattern,
             watchPath: absolute,
@@ -52,7 +54,9 @@ export function resolveSource(workspaceDir, configuredPath) {
         assertWorkspaceSourceHasNoSymlinkRoot(workspaceDir, configuredPath, root);
         return {
             collection: collectionName(absolute),
+            corpus,
             configuredPath,
+            kind: "files",
             root,
             pattern: isExactMarkdownFile ? basename(absolute) : "**/*.md",
             watchPath: absolute,
@@ -62,7 +66,33 @@ export function resolveSource(workspaceDir, configuredPath) {
     const root = prefix.slice(0, prefix.lastIndexOf(sep)) || sep;
     const pattern = relative(root, absolute).split(sep).join("/");
     assertWorkspaceSourceHasNoSymlinkRoot(workspaceDir, configuredPath, root);
-    return { collection: collectionName(absolute), configuredPath, root, pattern, watchPath: root };
+    return { collection: collectionName(absolute), corpus, configuredPath, kind: "files", root, pattern, watchPath: root };
+}
+export function resolveSessionSource(sessionsDir, chatTypes) {
+    return {
+        ...resolveSource(sessionsDir, sessionsDir, "sessions"),
+        configuredPath: sessionsDir,
+        kind: "sessions",
+        chatTypes,
+    };
+}
+export function resolveSources(workspaceDir, corpora) {
+    const sources = [];
+    const configured = new Map();
+    for (const corpus of corpora) {
+        for (const path of corpus.paths) {
+            const source = resolveSource(workspaceDir, path, corpus.name);
+            const identity = `${source.root}\0${source.pattern}`;
+            const duplicate = configured.get(identity);
+            if (duplicate) {
+                throw new Error(`unblock-memory source ${path} in corpus ${corpus.name} duplicates ` +
+                    `${duplicate.configuredPath} in corpus ${duplicate.corpus}`);
+            }
+            configured.set(identity, source);
+            sources.push(source);
+        }
+    }
+    return sources;
 }
 export function parseSafeVirtualPath(virtualPath, sources) {
     const match = /^qmd:\/\/([^/]+)\/(.+)$/.exec(virtualPath.trim());

package/openclaw.plugin.json

@@ -1,20 +1,21 @@
 {
   "id": "unblock-memory",
   "name": "Unblock Memory",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Indexes, retrieves, and analyzes configured workspace memory with existing QMD vectors.",
   "kind": "memory",
   "activation": { "onStartup": false },
-  "contracts": { "tools": ["memory_search", "memory_get", "memory_recluster", "memory_list_clusters", "memory_fetch_cluster"] },
+  "contracts": { "tools": ["memory_search", "memory_get", "memory_sync_sessions", "memory_recluster", "memory_list_clusters", "memory_fetch_cluster"] },
   "toolMetadata": {
+    "memory_sync_sessions": { "sideEffecting": true },
     "memory_recluster": { "sideEffecting": true },
     "memory_list_clusters": { "replaySafe": true },
     "memory_fetch_cluster": { "replaySafe": true }
   },
   "uiHints": {
-    "paths": {
-      "label": "Memory Paths",
-      "help": "Exact Markdown files, directories, or globs. Relative paths resolve from each agent workspace."
+    "corpora": {
+      "label": "Memory Corpora",
+      "help": "Named groups of exact Markdown files, directories, or globs. Relative paths resolve from each agent workspace."
     },
     "analysis.executable": {
       "label": "Memory Analysis Worker",
@@ -25,10 +26,49 @@
     "type": "object",
     "additionalProperties": false,
     "properties": {
-      "paths": {
+      "corpora": {
         "type": "array",
-        "items": { "type": "string", "minLength": 1 },
-        "default": ["MEMORY.md", "USER.md", "memory/**/*.md"]
+        "minItems": 1,
+        "items": {
+          "oneOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["name", "kind", "paths"],
+              "properties": {
+                "name": { "type": "string", "pattern": "\\S" },
+                "kind": { "const": "files" },
+                "paths": {
+                  "type": "array",
+                  "minItems": 1,
+                  "items": { "type": "string", "pattern": "\\S" }
+                }
+              }
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["name", "kind"],
+              "properties": {
+                "name": { "const": "sessions" },
+                "kind": { "const": "sessions" },
+                "chatTypes": {
+                  "type": "array",
+                  "minItems": 1,
+                  "items": { "enum": ["channel", "group", "direct"] },
+                  "default": ["channel", "group"]
+                }
+              }
+            }
+          ]
+        },
+        "default": [
+          {
+            "name": "memory",
+            "kind": "files",
+            "paths": ["MEMORY.md", "USER.md", "memory/**/*.md"]
+          }
+        ]
       },
       "analysis": {
         "type": "object",