openclaw-plugin-people-memory 0.0.0-stage → 0.0.2

package/dist/src/core/time.js

@@ -0,0 +1,27 @@
+function pad(value) {
+    return String(value).padStart(2, "0");
+}
+/** Local ISO timestamp with an explicit offset, matching the legacy data style. */
+export function nowIso(date = new Date()) {
+    const offsetMinutes = -date.getTimezoneOffset();
+    const sign = offsetMinutes >= 0 ? "+" : "-";
+    const abs = Math.abs(offsetMinutes);
+    return (`${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}` +
+        `T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}` +
+        `${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`);
+}
+export function dayKey(value = new Date()) {
+    if (value instanceof Date) {
+        return `${value.getFullYear()}-${pad(value.getMonth() + 1)}-${pad(value.getDate())}`;
+    }
+    const match = /^(\d{4}-\d{2}-\d{2})/.exec(value);
+    return match?.[1] ?? value.slice(0, 10);
+}
+export function isOlderThan(value, milliseconds) {
+    if (!value)
+        return true;
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed))
+        return true;
+    return Date.now() - parsed > milliseconds;
+}

package/dist/src/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/plugin/cli.js

@@ -0,0 +1,177 @@
+import { resolveWorkspaceRoot } from "../core/paths.js";
+import { describeCounts } from "../core/service.js";
+function printJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+function workspaceFor(api, options) {
+    const agentId = typeof options.agent === "string" ? options.agent : undefined;
+    const workspaceDir = (typeof options.workspace === "string" && options.workspace.trim()) ||
+        resolveWorkspaceRoot(api.config, agentId);
+    return { workspaceDir, agentId };
+}
+export function registerCli(api, runtime) {
+    if (typeof api.registerCli !== "function")
+        return;
+    api.registerCli(({ program }) => {
+        const people = program.command("people").description("Workspace-scoped people memory utilities");
+        people
+            .command("import")
+            .description("Re-import legacy JSON into the SQLite store (idempotent)")
+            .option("--workspace <path>", "Target workspace directory")
+            .option("--agent <id>", "Resolve workspace from an agent id")
+            .option("--force", "Re-import even if legacy data was imported before")
+            .option("--json", "Print JSON")
+            .action(async (options = {}) => {
+            const { workspaceDir, agentId } = workspaceFor(api, options);
+            const service = runtime.get({ workspaceDir, agentId });
+            const report = service.importLegacy(options.force === true);
+            if (options.json)
+                return printJson(report);
+            console.log(`导入: ${report.imported ? "完成" : "跳过"}${report.reason ? `（${report.reason}）` : ""}`);
+            console.log(`账号 ${report.accounts} · 人物 ${report.persons} · 绑定 ${report.bindings} · 群 ${report.groups} · 群记忆 ${report.groupEvents} · 印象 ${report.impressions} · 特征 ${report.traits}`);
+            if (report.warnings.length > 0)
+                console.log(`警告 ${report.warnings.length} 条`);
+        });
+        people
+            .command("status")
+            .description("Show people database status")
+            .option("--workspace <path>", "Target workspace directory")
+            .option("--agent <id>", "Resolve workspace from an agent id")
+            .option("--json", "Print JSON")
+            .action(async (options = {}) => {
+            const { workspaceDir, agentId } = workspaceFor(api, options);
+            const service = runtime.get({ workspaceDir, agentId });
+            const status = service.status();
+            if (options.json)
+                return printJson(status);
+            console.log(`工作区: ${status.workspaceDir}`);
+            console.log(`数据目录: ${status.dataDir}`);
+            console.log(`数据库: ${status.dbPath} (schema v${status.schemaVersion})`);
+            console.log(describeCounts(status.counts));
+            console.log(`最近全量扫描: ${status.lastFullScanAt ?? "无"}`);
+            console.log(`旧 JSON 导入: ${status.legacyImportedAt ?? "无"}`);
+        });
+        people
+            .command("validate")
+            .description("Validate people database integrity")
+            .option("--workspace <path>", "Target workspace directory")
+            .option("--agent <id>", "Resolve workspace from an agent id")
+            .option("--fix", "Repair safe issues")
+            .option("--json", "Print JSON")
+            .action(async (options = {}) => {
+            const { workspaceDir, agentId } = workspaceFor(api, options);
+            const service = runtime.get({ workspaceDir, agentId });
+            const actions = options.fix ? service.repair() : [];
+            const report = service.validate();
+            if (options.json)
+                return printJson({ ...report, repairActions: actions });
+            console.log(`${report.ok ? "OK" : "FAIL"} ${report.dbPath}`);
+            console.log(describeCounts(report.counts));
+            for (const issue of report.issues)
+                console.log(`[${issue.level}] ${issue.code}: ${issue.message}`);
+            for (const action of actions)
+                console.log(`[fix] ${action}`);
+        });
+        people
+            .command("bootstrap")
+            .description("Create the database and import legacy JSON when present")
+            .option("--workspace <path>", "Target workspace directory")
+            .option("--agent <id>", "Resolve workspace from an agent id")
+            .option("--json", "Print JSON")
+            .action(async (options = {}) => {
+            const { workspaceDir, agentId } = workspaceFor(api, options);
+            const status = runtime.get({ workspaceDir, agentId }).status();
+            if (options.json)
+                return printJson(status);
+            console.log(`已初始化: ${status.dbPath}`);
+            console.log(describeCounts(status.counts));
+            console.log(`旧 JSON 导入: ${status.legacyImportedAt ?? "无"}`);
+        });
+        people
+            .command("backup")
+            .description("Back up the SQLite store and export a JSON snapshot")
+            .option("--workspace <path>", "Target workspace directory")
+            .option("--agent <id>", "Resolve workspace from an agent id")
+            .option("--keep <n>", "Number of recent backup pairs to retain")
+            .option("--json", "Print JSON")
+            .action(async (options = {}) => {
+            const { workspaceDir, agentId } = workspaceFor(api, options);
+            const keep = options.keep ? Number(options.keep) : 14;
+            const report = runtime.get({ workspaceDir, agentId }).backup(keep);
+            if (options.json)
+                return printJson(report);
+            console.log(`备份目录: ${report.backupDir}`);
+            console.log(`SQLite: ${report.dbBackup} (${report.dbBytes} bytes)`);
+            console.log(`JSON: ${report.jsonBackup} (${report.jsonBytes} bytes)`);
+            console.log(`保留 ${report.kept} 份，清理旧文件 ${report.removedOld} 个`);
+        });
+        people
+            .command("health")
+            .description("Check maintenance risks without changing data")
+            .option("--workspace <path>", "Target workspace directory")
+            .option("--agent <id>", "Resolve workspace from an agent id")
+            .option("--json", "Print JSON")
+            .action(async (options = {}) => {
+            const { workspaceDir, agentId } = workspaceFor(api, options);
+            const report = runtime.get({ workspaceDir, agentId }).health();
+            if (options.json)
+                return printJson(report);
+            console.log(`${report.ok ? "OK" : "FAIL"} ${report.dbPath}`);
+            console.log(`最近备份: ${report.lastBackupAt ?? "无"}`);
+            console.log(describeCounts(report.counts));
+            for (const issue of report.issues)
+                console.log(`[${issue.level}] ${issue.code}: ${issue.message}`);
+        });
+        people
+            .command("cycle")
+            .description("Run one plugin-owned maintenance cycle")
+            .option("--workspace <path>", "Target workspace directory")
+            .option("--agent <id>", "Resolve workspace from an agent id")
+            .option("--keep <n>", "Number of recent backup pairs to retain")
+            .option("--interval-hours <n>", "Minimum hours between automatic backups")
+            .option("--force-backup", "Create a backup even when one is recent")
+            .option("--json", "Print JSON")
+            .action(async (options = {}) => {
+            const { workspaceDir, agentId } = workspaceFor(api, options);
+            const report = runtime.get({ workspaceDir, agentId }).cycle({
+                backupKeep: options.keep ? Number(options.keep) : 14,
+                backupIntervalHours: options.intervalHours ? Number(options.intervalHours) : 20,
+                forceBackup: options.forceBackup === true,
+            });
+            if (options.json)
+                return printJson(report);
+            console.log(`周期: ${report.cycledAt}`);
+            console.log(report.backup ? `备份: ${report.backup.dbBackup}` : "备份: 跳过");
+            console.log(`自动修复: ${report.repairActions.length ? report.repairActions.join("；") : "无"}`);
+            console.log(`健康: ${report.health.ok ? "ok" : "error"}，待办 ${report.actions.length} 项`);
+            for (const action of report.actions)
+                console.log(`[${action.kind}] ${action.target}: ${action.message}`);
+        });
+        people
+            .command("search")
+            .description("Search accounts, persons, impressions and group events")
+            .option("--query <text>", "Search text")
+            .option("--workspace <path>", "Target workspace directory")
+            .option("--agent <id>", "Resolve workspace from an agent id")
+            .option("--limit <n>", "Maximum hits per section")
+            .option("--json", "Print JSON")
+            .action(async (options = {}) => {
+            if (!options.query?.trim())
+                throw new Error("--query is required");
+            const { workspaceDir, agentId } = workspaceFor(api, options);
+            const limit = options.limit ? Number(options.limit) : 10;
+            const report = runtime.get({ workspaceDir, agentId }).search(options.query, limit);
+            if (options.json)
+                return printJson(report);
+            console.log(`账号 ${report.accounts.length} · 人物 ${report.persons.length} · 印象 ${report.impressions.length} · 群事件 ${report.groupEvents.length}`);
+            for (const account of report.accounts)
+                console.log(`账号 ${account.account_id} (${account.display_name ?? "?"})`);
+            for (const person of report.persons)
+                console.log(`人物 ${person.person_id} (${person.name ?? "?"})`);
+            for (const impression of report.impressions)
+                console.log(`印象 ${impression.owner_id}: ${impression.content}`);
+            for (const event of report.groupEvents)
+                console.log(`群事件 ${event.group_id}: ${event.summary}`);
+        });
+    }, { commands: ["people"] });
+}

package/dist/src/plugin/config.js

@@ -0,0 +1,64 @@
+export function normalizeConfig(raw) {
+    const value = (raw ?? {});
+    const str = (key, fallback) => typeof value[key] === "string" && value[key].trim()
+        ? value[key].trim()
+        : fallback;
+    const bool = (key, fallback) => typeof value[key] === "boolean" ? value[key] : fallback;
+    const list = (key) => Array.isArray(value[key])
+        ? value[key].filter((item) => typeof item === "string")
+        : [];
+    const record = (key) => {
+        const rawRecord = value[key];
+        if (!rawRecord || typeof rawRecord !== "object" || Array.isArray(rawRecord))
+            return {};
+        return Object.fromEntries(Object.entries(rawRecord).filter((entry) => typeof entry[1] === "string"));
+    };
+    return {
+        dataDir: str("dataDir", "{stateDir}/plugins/people/{workspaceKey}"),
+        workspaceDataDirs: record("workspaceDataDirs"),
+        databaseFile: str("databaseFile", "people.db"),
+        injectContext: bool("injectContext", true),
+        injectGroupMemory: bool("injectGroupMemory", true),
+        injectMaxChars: typeof value.injectMaxChars === "number" && value.injectMaxChars > 200
+            ? value.injectMaxChars
+            : 1200,
+        disabledAgents: list("disabledAgents"),
+        capture: bool("capture", true),
+        captureGroups: bool("captureGroups", true),
+        captureSkipSenders: (() => {
+            const skip = list("captureSkipSenders");
+            return skip.length ? skip : undefined;
+        })(),
+        importLegacy: bool("importLegacy", true),
+        platformTemplate: str("platformTemplate", "{channel}/{account}"),
+        multiAccountChannels: (() => {
+            const channels = list("multiAccountChannels");
+            return channels.length ? channels : undefined;
+        })(),
+        platformOverrides: record("platformOverrides"),
+        senderFamilies: (() => {
+            const raw = value.senderFamilies;
+            if (raw === undefined)
+                return undefined;
+            if (!Array.isArray(raw))
+                return undefined;
+            const families = [];
+            for (const family of raw) {
+                if (!Array.isArray(family))
+                    continue;
+                const labels = family
+                    .filter((item) => typeof item === "string" && Boolean(item.trim()))
+                    .map((item) => item.trim());
+                if (labels.length >= 2)
+                    families.push(labels);
+            }
+            return families.length > 0 ? families : undefined;
+        })(),
+        debug: bool("debug", false),
+    };
+}
+export function isAgentDisabled(config, agentId) {
+    if (!agentId)
+        return false;
+    return (config.disabledAgents ?? []).some((value) => value.trim() === agentId);
+}

package/dist/src/plugin/hooks.js

@@ -0,0 +1,101 @@
+import { isAgentDisabled } from "./config.js";
+import { hookChatId, hookChatTitle, hookIsGroup, hookPlatform, hookSenderName, inboundGroupTitle, inboundPlatform, } from "./identity.js";
+const CAPTURE_INTERVAL_MS = 30_000;
+export function registerHooks(api, runtime) {
+    const lastCapture = new Map();
+    const pendingIdentity = new Map();
+    api.on("inbound_claim", ((event) => {
+        try {
+            const senderId = event.senderId?.trim();
+            if (!senderId)
+                return undefined;
+            const platform = inboundPlatform(event, runtime.config);
+            const at = Date.now();
+            const entry = {
+                senderName: event.senderName?.trim() || undefined,
+                chatTitle: inboundGroupTitle(event),
+                isGroup: event.isGroup === true,
+                at,
+            };
+            pendingIdentity.set(`${platform}:${senderId}`, entry);
+            if (event.sessionKey)
+                pendingIdentity.set(`session:${event.sessionKey}`, entry);
+            if (pendingIdentity.size > 500) {
+                for (const [key, value] of pendingIdentity) {
+                    if (at - value.at > 10 * 60_000)
+                        pendingIdentity.delete(key);
+                }
+            }
+        }
+        catch {
+            // passive observer only
+        }
+        return undefined;
+    }));
+    api.on("before_prompt_build", ((event, ctx) => {
+        try {
+            if (isAgentDisabled(runtime.config, ctx.agentId))
+                return undefined;
+            const senderId = ctx.senderId?.trim();
+            if (!senderId)
+                return undefined;
+            const service = runtime.get({
+                workspaceDir: ctx.workspaceDir,
+                agentId: ctx.agentId,
+                agentDir: undefined,
+            });
+            const platform = hookPlatform(ctx, runtime.config);
+            const chatId = hookChatId(ctx);
+            const pending = pendingIdentity.get(`${platform}:${senderId}`) ??
+                (ctx.sessionKey ? pendingIdentity.get(`session:${ctx.sessionKey}`) : undefined);
+            const chatTitle = hookChatTitle(ctx) ?? pending?.chatTitle;
+            const isGroup = hookIsGroup(ctx) || pending?.isGroup === true;
+            let groupId;
+            if (runtime.config.capture !== false) {
+                const captureKey = `${service.paths.workspaceKey}|${platform}|${senderId}`;
+                const now = Date.now();
+                const previous = lastCapture.get(captureKey) ?? 0;
+                if (now - previous >= CAPTURE_INTERVAL_MS) {
+                    lastCapture.set(captureKey, now);
+                    const result = service.capture({
+                        platform,
+                        senderId,
+                        senderName: hookSenderName(ctx) ?? pending?.senderName,
+                        chatId,
+                        chatTitle,
+                        isGroup,
+                        agentId: ctx.agentId,
+                    });
+                    groupId = result.groupId;
+                }
+            }
+            if (runtime.config.injectContext === false)
+                return undefined;
+            if (!groupId && chatId) {
+                groupId = service.db.findGroup(platform, chatId)?.group_id;
+            }
+            const accountId = service.resolveAccountForLookup(platform, senderId)?.account_id;
+            if (!accountId)
+                return undefined;
+            const card = service.contextCard({
+                accountId,
+                groupId,
+                maxChars: runtime.config.injectMaxChars,
+                includeGroupMemory: runtime.config.injectGroupMemory !== false,
+            });
+            if (!card)
+                return undefined;
+            if (runtime.config.debug) {
+                runtime.api.logger.info(`[people] inject ${accountId} bytes=${card.length} promptBytes=${event.prompt.length}`);
+            }
+            return { prependContext: card };
+        }
+        catch (error) {
+            runtime.api.logger.warn(`[people] before_prompt_build failed: ${error.message}`);
+            return undefined;
+        }
+    }), { timeoutMs: 3000 });
+    api.on("gateway_stop", () => {
+        runtime.closeAll();
+    });
+}

package/dist/src/plugin/identity.js

@@ -0,0 +1,77 @@
+import { resolvePlatform } from "../core/platform.js";
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function firstString(source, keys) {
+    for (const key of keys) {
+        const value = source[key];
+        if (typeof value === "string" && value.trim())
+            return value.trim();
+    }
+    return undefined;
+}
+export function hookSenderName(ctx) {
+    const sender = record(ctx.channelContext?.sender);
+    return firstString(sender, [
+        "name",
+        "displayName",
+        "display_name",
+        "nickname",
+        "username",
+        "userName",
+        "remark",
+    ]);
+}
+export function hookChatId(ctx) {
+    const chat = record(ctx.channelContext?.chat);
+    return ctx.chatId?.trim() || firstString(chat, ["id", "chatId", "chat_id", "conversationId"]);
+}
+export function hookChatTitle(ctx) {
+    const chat = record(ctx.channelContext?.chat);
+    return firstString(chat, [
+        "title",
+        "name",
+        "displayName",
+        "display_name",
+        "subject",
+        "group_subject",
+        "groupName",
+    ]);
+}
+export function hookIsGroup(ctx) {
+    const chat = record(ctx.channelContext?.chat);
+    if (chat.isGroup === true || chat.is_group_chat === true || chat.isGroupChat === true)
+        return true;
+    const type = firstString(chat, ["type", "kind", "chat_type", "chatType"]);
+    return type === "group" || type === "channel" || type === "supergroup";
+}
+export function hookPlatform(ctx, config) {
+    const chat = record(ctx.channelContext?.chat);
+    const sender = record(ctx.channelContext?.sender);
+    const metadataPlatform = firstString(chat, ["platform", "provider"]) ?? firstString(sender, ["platform", "provider"]);
+    return resolvePlatform({
+        channel: ctx.channel,
+        provider: ctx.messageProvider,
+        accountId: ctx.accountId,
+        metadataPlatform,
+        template: config.platformTemplate,
+        overrides: config.platformOverrides,
+    });
+}
+export function inboundPlatform(event, config) {
+    const metadata = record(event.metadata);
+    const metadataPlatform = firstString(metadata, ["platform", "provider"]) ??
+        firstString(record(metadata.chat), ["platform", "provider"]);
+    return resolvePlatform({
+        channel: event.channel,
+        accountId: event.accountId,
+        metadataPlatform,
+        template: config.platformTemplate,
+        overrides: config.platformOverrides,
+    });
+}
+export function inboundGroupTitle(event) {
+    const metadata = record(event.metadata);
+    return (firstString(metadata, ["group_subject", "groupSubject", "groupName", "group_name"]) ??
+        firstString(record(metadata.chat), ["title", "name", "subject"]));
+}

package/dist/src/plugin/runtime.js

@@ -0,0 +1,72 @@
+import fs from "node:fs";
+import { resolveStorePaths, resolveWorkspaceRoot } from "../core/paths.js";
+import { PeopleService } from "../core/service.js";
+import { normalizeConfig } from "./config.js";
+export class PeopleRuntime {
+    api;
+    config;
+    cache = new Map();
+    constructor(api) {
+        this.api = api;
+        this.config = normalizeConfig(api.pluginConfig);
+    }
+    resolveStateDir() {
+        try {
+            return this.api.runtime?.state?.resolveStateDir?.(process.env);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    logDebug(message) {
+        if (this.config.debug)
+            this.api.logger.info(`[people] ${message}`);
+    }
+    get(context) {
+        const workspaceDir = context.workspaceDir?.trim() ||
+            resolveWorkspaceRoot(this.api.config, context.agentId);
+        const paths = resolveStorePaths({
+            workspaceDir,
+            agentId: context.agentId,
+            agentDir: context.agentDir,
+            stateDir: this.resolveStateDir(),
+            config: this.config,
+        });
+        const key = paths.workspaceKey;
+        const existing = this.cache.get(key);
+        if (existing && fs.existsSync(existing.paths.dbPath))
+            return existing;
+        if (existing) {
+            try {
+                existing.close();
+            }
+            catch {
+                // ignore
+            }
+            this.cache.delete(key);
+        }
+        this.logDebug(`open ${paths.dbPath} (agent=${context.agentId ?? "?"})`);
+        const service = new PeopleService({
+            paths,
+            config: this.config,
+            logger: {
+                info: (message) => this.api.logger.info(message),
+                warn: (message) => this.api.logger.warn(message),
+                debug: (message) => this.logDebug(message),
+            },
+        });
+        this.cache.set(key, service);
+        return service;
+    }
+    closeAll() {
+        for (const service of this.cache.values()) {
+            try {
+                service.close();
+            }
+            catch {
+                // ignore
+            }
+        }
+        this.cache.clear();
+    }
+}