@gralkor/openclaw 4.0.0

package/dist/register.js

@@ -0,0 +1,184 @@
+import { GralkorHttpClient, createServerManager, sanitizeGroupId, waitForHealth, GRALKOR_URL, } from "./gralkor/index.js";
+import { buildSecretEnv } from "./config.js";
+import { runMemorySearch } from "./tools/memory-search.js";
+import { runMemoryAdd } from "./tools/memory-add.js";
+import { runMemoryBuildIndices } from "./tools/memory-build-indices.js";
+import { runMemoryBuildCommunities } from "./tools/memory-build-communities.js";
+import { runBeforePromptBuild } from "./hooks/before-prompt-build.js";
+import { runAgentEnd } from "./hooks/agent-end.js";
+import { runSessionEnd } from "./hooks/session-end.js";
+import { runNativeIndexer } from "./native-indexer.js";
+import { requireSessionKey } from "./session-map.js";
+export function registerTools(api, client, config) {
+    api.registerTool((ctx) => {
+        const rawSessionKey = ctx?.sessionKey;
+        return [
+            {
+                name: "memory_search",
+                description: "Search long-term memory for relevant context. Use specific, focused queries.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        query: { type: "string", description: "The search query" },
+                    },
+                    required: ["query"],
+                },
+                execute: async (_toolCallId, args) => {
+                    const r = await runMemorySearch(client, {
+                        query: args.query,
+                        sessionKey: requireSessionKey(rawSessionKey),
+                        agentName: config.agentName,
+                        maxResults: config.search.maxResults,
+                    });
+                    if ("error" in r)
+                        throw new Error(JSON.stringify(r.error));
+                    return r.ok;
+                },
+            },
+            {
+                name: "memory_add",
+                description: "Store a thought, insight, reflection, or decision in long-term memory.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        content: { type: "string" },
+                        source_description: { type: "string" },
+                    },
+                    required: ["content"],
+                },
+                execute: async (_toolCallId, args) => {
+                    const r = await runMemoryAdd(client, {
+                        sessionKey: requireSessionKey(rawSessionKey),
+                        content: args.content,
+                        sourceDescription: args.source_description,
+                    });
+                    if ("error" in r)
+                        throw new Error(JSON.stringify(r.error));
+                    return "Queued for storage.";
+                },
+            },
+            {
+                name: "memory_build_indices",
+                description: "ADMIN — DO NOT CALL unless the user has explicitly asked you to rebuild Gralkor's graph search indices. This is an operator-maintenance action; calling it unprompted wastes time without improving anything the user will notice. Idempotent rebuild of the graph search indices.",
+                parameters: { type: "object", properties: {} },
+                execute: async () => {
+                    const r = await runMemoryBuildIndices(client);
+                    if ("error" in r)
+                        throw new Error(JSON.stringify(r.error));
+                    return `Indices rebuilt (${r.ok.status}).`;
+                },
+            },
+            {
+                name: "memory_build_communities",
+                description: "ADMIN — DO NOT CALL unless the user has explicitly asked you to build Gralkor communities. This is an expensive operator-maintenance action; calling it unprompted wastes time. Runs Graphiti community detection over this agent's memory partition.",
+                parameters: { type: "object", properties: {} },
+                execute: async () => {
+                    const r = await runMemoryBuildCommunities(client, {
+                        sessionKey: requireSessionKey(rawSessionKey),
+                    });
+                    if ("error" in r)
+                        throw new Error(JSON.stringify(r.error));
+                    return `Built ${r.ok.communities} communities across ${r.ok.edges} edges.`;
+                },
+            },
+        ];
+    });
+}
+export function registerHooks(api, client, config) {
+    api.on("before_prompt_build", async (event, ctx) => {
+        const sessionKey = requireSessionKey(ctx.sessionKey);
+        const agentId = ctx.agentId ?? sessionKey;
+        const workspaceDir = ctx.workspaceDir ?? config.workspaceDir;
+        if (workspaceDir) {
+            void runNativeIndexer(client, workspaceDir, sanitizeGroupId(agentId)).catch((err) => {
+                console.error("[gralkor] native-index error:", err);
+            });
+        }
+        const result = await runBeforePromptBuild(client, {
+            sessionKey,
+            agentId,
+            agentName: config.agentName,
+            prompt: event.prompt ?? "",
+        });
+        if ("error" in result)
+            throw new Error(JSON.stringify(result.error));
+        return result.ok;
+    });
+    api.on("agent_end", async (event, ctx) => {
+        const sessionKey = requireSessionKey(ctx.sessionKey);
+        const result = await runAgentEnd(client, {
+            sessionKey,
+            agentName: config.agentName,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            messages: (event.messages ?? []),
+        });
+        if ("error" in result)
+            throw new Error(JSON.stringify(result.error));
+    });
+    api.on("session_end", async (_event, ctx) => {
+        const sessionKey = requireSessionKey(ctx.sessionKey);
+        const result = await runSessionEnd(client, { sessionKey });
+        if ("error" in result)
+            throw new Error(JSON.stringify(result.error));
+    });
+}
+let cachedManager = null;
+export function resetServerManagerForTests() {
+    cachedManager = null;
+}
+const MEMORY_TOOL_PROMPT_LINES = [
+    "Memory is stored in a Graphiti knowledge graph backed by FalkorDB.",
+    "Use `memory_search` to recall prior facts before answering questions about past decisions, dates, people, preferences, or todos.",
+    "Use `memory_add` to store new insights, reflections, or durable decisions you want available in future sessions.",
+];
+/**
+ * Declares this plugin as the active memory capability for OpenClaw 2026.5.x+.
+ * Once registered, `openclaw plugins info` reports `Shape: memory capability`
+ * and OpenClaw routes the `plugins.slots.memory` slot through this plugin.
+ *
+ * The capability is intentionally minimal — capture/recall is hook+tool-driven
+ * (see registerHooks / registerTools). The promptBuilder only contributes the
+ * static usage hints that the agent reads alongside the tool definitions, and
+ * flushPlanResolver opts out of OpenClaw's compaction-flush turn (we capture
+ * per agent_end, so a follow-up flush turn would duplicate the work).
+ */
+export function registerMemoryCapability(api) {
+    if (typeof api.registerMemoryCapability !== "function")
+        return;
+    api.registerMemoryCapability({
+        promptBuilder: () => MEMORY_TOOL_PROMPT_LINES,
+        flushPlanResolver: () => null,
+    });
+}
+export function registerServerService(api, config, version, wheelRepo) {
+    if (!config.dataDir) {
+        throw new Error("[gralkor] dataDir is required — set plugins.entries.openclaw-gralkor.config.dataDir");
+    }
+    // OpenClaw 2026.5.x hot-reloads the plugin module on every agent run; the
+    // hook/tool/service bindings must happen on each load (the new registry is
+    // empty), but the underlying Python uvicorn process must be a singleton
+    // for the process lifetime. Module-level slot achieves that — the slot
+    // clears when the module is re-imported in a new process, never within one.
+    const manager = (cachedManager ??= createServerManager({
+        dataDir: config.dataDir,
+        port: 4000,
+        version,
+        wheelRepo,
+        secretEnv: buildSecretEnv(config),
+        llmConfig: config.llm,
+        embedderConfig: config.embedder,
+        ontologyConfig: config.ontology,
+        test: config.test,
+    }));
+    api.registerService({
+        id: "gralkor-server",
+        start: async () => {
+            await manager.start();
+            const client = new GralkorHttpClient({ baseUrl: GRALKOR_URL });
+            await waitForHealth(client, { timeoutMs: 120_000, backoffMs: 500 });
+        },
+        stop: () => manager.stop(),
+    });
+    return manager;
+}
+//# sourceMappingURL=register.js.map

package/dist/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":"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"}

package/dist/session-map.d.ts

@@ -0,0 +1,13 @@
+export declare function setSessionGroup(sessionKey: string, agentId: string): void;
+export declare function getSessionGroup(sessionKey: string): string | null;
+/**
+ * Gralkor requires a non-blank session_id at every boundary. Call this
+ * at the top of each hook and inside each tool's execute — there is no
+ * "default" bucket and no silent fallback. If OpenClaw dispatches an
+ * event without a sessionKey, that's a bug in the caller's lifecycle,
+ * not something this plugin masks.
+ */
+export declare function requireSessionKey(sessionKey: string | undefined | null): string;
+/** Reset module-level state. Test-only. */
+export declare function resetSessionMap(): void;
+//# sourceMappingURL=session-map.d.ts.map

package/dist/session-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-map.d.ts","sourceRoot":"","sources":["../src/session-map.ts"],"names":[],"mappings":"AAUA,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAEzE;AAED,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEjE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAO/E;AAED,2CAA2C;AAC3C,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}

package/dist/session-map.js

@@ -0,0 +1,32 @@
+import { sanitizeGroupId } from "./gralkor/index.js";
+/**
+ * Module-level session → group map. Shared across all plugin instances
+ * in the process — OpenClaw reloads plugins multiple times per event,
+ * and a per-instance map would lose state on each reload. Module scope
+ * survives reloads within the same Node process.
+ */
+const sessionGroups = new Map();
+export function setSessionGroup(sessionKey, agentId) {
+    sessionGroups.set(sessionKey, sanitizeGroupId(agentId));
+}
+export function getSessionGroup(sessionKey) {
+    return sessionGroups.get(sessionKey) ?? null;
+}
+/**
+ * Gralkor requires a non-blank session_id at every boundary. Call this
+ * at the top of each hook and inside each tool's execute — there is no
+ * "default" bucket and no silent fallback. If OpenClaw dispatches an
+ * event without a sessionKey, that's a bug in the caller's lifecycle,
+ * not something this plugin masks.
+ */
+export function requireSessionKey(sessionKey) {
+    if (typeof sessionKey !== "string" || sessionKey.length === 0) {
+        throw new Error("Gralkor requires a non-blank session_id; OpenClaw did not provide a sessionKey");
+    }
+    return sessionKey;
+}
+/** Reset module-level state. Test-only. */
+export function resetSessionMap() {
+    sessionGroups.clear();
+}
+//# sourceMappingURL=session-map.js.map

package/dist/session-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-map.js","sourceRoot":"","sources":["../src/session-map.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;GAKG;AACH,MAAM,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;AAEhD,MAAM,UAAU,eAAe,CAAC,UAAkB,EAAE,OAAe;IACjE,aAAa,CAAC,GAAG,CAAC,UAAU,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,UAAkB;IAChD,OAAO,aAAa,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC;AAC/C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAqC;IACrE,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CACb,gFAAgF,CACjF,CAAC;IACJ,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,eAAe;IAC7B,aAAa,CAAC,KAAK,EAAE,CAAC;AACxB,CAAC"}

package/dist/tools/memory-add.d.ts

@@ -0,0 +1,15 @@
+import type { GralkorClient, Result } from "../gralkor/index.js";
+export interface MemoryAddArgs {
+    sessionKey: string;
+    content: string;
+    sourceDescription?: string;
+}
+/**
+ * The `memory_add` ReAct tool. Thin wrapper around
+ * `GralkorClient.memoryAdd`. The server queues the add for async ingest
+ * (Graphiti entity/edge extraction is slow) so the client side returns
+ * as soon as the HTTP 2xx comes back; that's what `{ ok: true }` means
+ * here.
+ */
+export declare function runMemoryAdd(client: GralkorClient, args: MemoryAddArgs): Promise<Result<true>>;
+//# sourceMappingURL=memory-add.d.ts.map

package/dist/tools/memory-add.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-add.d.ts","sourceRoot":"","sources":["../../src/tools/memory-add.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAGjE,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAKvB"}

package/dist/tools/memory-add.js

@@ -0,0 +1,15 @@
+import { getSessionGroup } from "../session-map.js";
+/**
+ * The `memory_add` ReAct tool. Thin wrapper around
+ * `GralkorClient.memoryAdd`. The server queues the add for async ingest
+ * (Graphiti entity/edge extraction is slow) so the client side returns
+ * as soon as the HTTP 2xx comes back; that's what `{ ok: true }` means
+ * here.
+ */
+export async function runMemoryAdd(client, args) {
+    const groupId = getSessionGroup(args.sessionKey);
+    if (groupId === null)
+        return { error: "session_not_registered" };
+    return client.memoryAdd(groupId, args.content, args.sourceDescription ?? null);
+}
+//# sourceMappingURL=memory-add.js.map

package/dist/tools/memory-add.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-add.js","sourceRoot":"","sources":["../../src/tools/memory-add.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAQpD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAqB,EACrB,IAAmB;IAEnB,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACjD,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,wBAAwB,EAAE,CAAC;IAEjE,OAAO,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,iBAAiB,IAAI,IAAI,CAAC,CAAC;AACjF,CAAC"}

package/dist/tools/memory-build-communities.d.ts

@@ -0,0 +1,19 @@
+import type { GralkorClient, Result } from "../gralkor/index.js";
+export interface MemoryBuildCommunitiesArgs {
+    sessionKey: string;
+}
+/**
+ * The `memory_build_communities` admin tool. Thin wrapper around
+ * `GralkorClient.buildCommunities`. Runs Graphiti's community detection
+ * over the session's group partition — expensive-ish but improves search
+ * quality by clustering related entities.
+ *
+ * Per-group rather than whole-graph, so the session must be registered
+ * (via `before_prompt_build`) before this can fire. Returns
+ * `session_not_registered` rather than silently routing to `"default"`.
+ */
+export declare function runMemoryBuildCommunities(client: GralkorClient, args: MemoryBuildCommunitiesArgs): Promise<Result<{
+    communities: number;
+    edges: number;
+}>>;
+//# sourceMappingURL=memory-build-communities.d.ts.map

package/dist/tools/memory-build-communities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-build-communities.d.ts","sourceRoot":"","sources":["../../src/tools/memory-build-communities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAGjE,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,0BAA0B,GAC/B,OAAO,CAAC,MAAM,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAKzD"}

package/dist/tools/memory-build-communities.js

@@ -0,0 +1,18 @@
+import { getSessionGroup } from "../session-map.js";
+/**
+ * The `memory_build_communities` admin tool. Thin wrapper around
+ * `GralkorClient.buildCommunities`. Runs Graphiti's community detection
+ * over the session's group partition — expensive-ish but improves search
+ * quality by clustering related entities.
+ *
+ * Per-group rather than whole-graph, so the session must be registered
+ * (via `before_prompt_build`) before this can fire. Returns
+ * `session_not_registered` rather than silently routing to `"default"`.
+ */
+export async function runMemoryBuildCommunities(client, args) {
+    const groupId = getSessionGroup(args.sessionKey);
+    if (groupId === null)
+        return { error: "session_not_registered" };
+    return client.buildCommunities(groupId);
+}
+//# sourceMappingURL=memory-build-communities.js.map

package/dist/tools/memory-build-communities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-build-communities.js","sourceRoot":"","sources":["../../src/tools/memory-build-communities.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAMpD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,MAAqB,EACrB,IAAgC;IAEhC,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACjD,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,wBAAwB,EAAE,CAAC;IAEjE,OAAO,MAAM,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC1C,CAAC"}

package/dist/tools/memory-build-indices.d.ts

@@ -0,0 +1,12 @@
+import type { GralkorClient, Result } from "../gralkor/index.js";
+/**
+ * The `memory_build_indices` admin tool. Thin wrapper around
+ * `GralkorClient.buildIndices`. Rebuilds the Graphiti search indices —
+ * idempotent, safe to run any time, but only useful after schema changes
+ * or when search behaviour looks stale. Operates across the whole graph
+ * (not per-group).
+ */
+export declare function runMemoryBuildIndices(client: GralkorClient): Promise<Result<{
+    status: string;
+}>>;
+//# sourceMappingURL=memory-build-indices.d.ts.map

package/dist/tools/memory-build-indices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-build-indices.d.ts","sourceRoot":"","sources":["../../src/tools/memory-build-indices.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAEjE;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,MAAM,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAErC"}

package/dist/tools/memory-build-indices.js

@@ -0,0 +1,11 @@
+/**
+ * The `memory_build_indices` admin tool. Thin wrapper around
+ * `GralkorClient.buildIndices`. Rebuilds the Graphiti search indices —
+ * idempotent, safe to run any time, but only useful after schema changes
+ * or when search behaviour looks stale. Operates across the whole graph
+ * (not per-group).
+ */
+export async function runMemoryBuildIndices(client) {
+    return client.buildIndices();
+}
+//# sourceMappingURL=memory-build-indices.js.map

package/dist/tools/memory-build-indices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-build-indices.js","sourceRoot":"","sources":["../../src/tools/memory-build-indices.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAqB;IAErB,OAAO,MAAM,CAAC,YAAY,EAAE,CAAC;AAC/B,CAAC"}

package/dist/tools/memory-search.d.ts

@@ -0,0 +1,20 @@
+import type { GralkorClient, Result } from "../gralkor/index.js";
+export interface MemorySearchArgs {
+    query: string;
+    sessionKey: string;
+    agentName: string;
+    /** Max facts to interpret. Forwarded as max_results. Omit to use the server default. */
+    maxResults?: number;
+}
+/**
+ * The `memory_search` ReAct tool. Calls `GralkorClient.recall` — the
+ * same path the `before_prompt_build` hook uses for auto-recall. There
+ * is no separate manual-search endpoint.
+ *
+ * Returns the recalled memory block (the server always wraps a block;
+ * "no facts" and "no relevant facts" both collapse to a
+ * `"No relevant memories found."` body inside the same envelope), and
+ * surfaces session-map / client errors otherwise.
+ */
+export declare function runMemorySearch(client: GralkorClient, args: MemorySearchArgs): Promise<Result<string>>;
+//# sourceMappingURL=memory-search.d.ts.map

package/dist/tools/memory-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-search.d.ts","sourceRoot":"","sources":["../../src/tools/memory-search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAGjE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAWzB"}

package/dist/tools/memory-search.js

@@ -0,0 +1,18 @@
+import { getSessionGroup } from "../session-map.js";
+/**
+ * The `memory_search` ReAct tool. Calls `GralkorClient.recall` — the
+ * same path the `before_prompt_build` hook uses for auto-recall. There
+ * is no separate manual-search endpoint.
+ *
+ * Returns the recalled memory block (the server always wraps a block;
+ * "no facts" and "no relevant facts" both collapse to a
+ * `"No relevant memories found."` body inside the same envelope), and
+ * surfaces session-map / client errors otherwise.
+ */
+export async function runMemorySearch(client, args) {
+    const groupId = getSessionGroup(args.sessionKey);
+    if (groupId === null)
+        return { error: "session_not_registered" };
+    return client.recall(groupId, args.sessionKey, args.query, args.agentName, args.maxResults);
+}
+//# sourceMappingURL=memory-search.js.map

package/dist/tools/memory-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-search.js","sourceRoot":"","sources":["../../src/tools/memory-search.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAUpD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAqB,EACrB,IAAsB;IAEtB,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACjD,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,EAAE,KAAK,EAAE,wBAAwB,EAAE,CAAC;IAEjE,OAAO,MAAM,CAAC,MAAM,CAClB,OAAO,EACP,IAAI,CAAC,UAAU,EACf,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,SAAS,EACd,IAAI,CAAC,UAAU,CAChB,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * OpenClaw plugin API surface used by this plugin.
+ *
+ * OpenClaw doesn't export types, so we define the subset we use here.
+ * Keep in sync with the OpenClaw plugin contract.
+ */
+type AnyFn = (...args: any[]) => any;
+export type RegistrationMode = "full" | "setup-only" | "setup-runtime" | "cli-metadata";
+export interface MemoryPluginApi {
+    pluginConfig?: Record<string, unknown>;
+    registrationMode?: RegistrationMode;
+    on(event: string, handler: AnyFn): void;
+    registerService(service: {
+        id: string;
+        start: () => void | Promise<void>;
+        stop: () => void | Promise<void>;
+    }): void;
+    registerCli(registrar: (ctx: {
+        program: any;
+        config: any;
+        workspaceDir?: string;
+        logger: any;
+    }) => void | Promise<void>, opts?: {
+        commands?: string[];
+    }): void;
+    registerTool(tool: {
+        name: string;
+        description: string;
+        parameters: unknown;
+        execute: AnyFn;
+    }, opts?: {
+        optional?: boolean;
+    }): void;
+    registerTool(factory: (ctx: any) => any | any[] | null, opts?: {
+        names?: string[];
+    }): void;
+    /**
+     * Declare this plugin as the active memory capability. OpenClaw 2026.5.x
+     * routes the `plugins.slots.memory` slot owner through this surface — once
+     * called, `openclaw plugins info` reports `Shape: memory capability`. All
+     * fields are optional; an empty object is enough for slot ownership.
+     *
+     * `promptBuilder` is invoked synchronously during system-prompt assembly
+     * with `{ availableTools, citationsMode }` and returns static lines (no
+     * session/query context — recall is agent-driven via `memory_search`).
+     * `flushPlanResolver` is invoked synchronously at compaction time; return
+     * `null` to opt out of OpenClaw's compaction-flush turn (we capture per
+     * agent_end hook, so the flush turn would be redundant).
+     */
+    registerMemoryCapability?(capability: {
+        promptBuilder?: (params: {
+            availableTools?: readonly string[];
+            citationsMode?: string;
+        }) => readonly string[];
+        flushPlanResolver?: (params: {
+            cfg?: unknown;
+            nowMs?: number;
+        }) => Record<string, unknown> | null;
+    }): void;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,KAAK,KAAK,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;AAErC,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,YAAY,GAAG,eAAe,GAAG,cAAc,CAAC;AAExF,MAAM,WAAW,eAAe;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,GAAG,IAAI,CAAC;IACxC,eAAe,CAAC,OAAO,EAAE;QACvB,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KAClC,GAAG,IAAI,CAAC;IACT,WAAW,CACT,SAAS,EAAE,CAAC,GAAG,EAAE;QAEf,OAAO,EAAE,GAAG,CAAC;QAEb,MAAM,EAAE,GAAG,CAAC;QACZ,YAAY,CAAC,EAAE,MAAM,CAAC;QAEtB,MAAM,EAAE,GAAG,CAAC;KACb,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EAC1B,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAC7B,IAAI,CAAC;IACR,YAAY,CACV,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,KAAK,CAAA;KAAE,EAChF,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAC5B,IAAI,CAAC;IACR,YAAY,CAEV,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,GAAG,GAAG,EAAE,GAAG,IAAI,EACzC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAC1B,IAAI,CAAC;IACR;;;;;;;;;;;;OAYG;IACH,wBAAwB,CAAC,CAAC,UAAU,EAAE;QACpC,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE;YACvB,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;YACnC,aAAa,CAAC,EAAE,MAAM,CAAC;SACxB,KAAK,SAAS,MAAM,EAAE,CAAC;QACxB,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE;YAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;YACd,KAAK,CAAC,EAAE,MAAM,CAAC;SAChB,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;KACtC,GAAG,IAAI,CAAC;CACV"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * OpenClaw plugin API surface used by this plugin.
+ *
+ * OpenClaw doesn't export types, so we define the subset we use here.
+ * Keep in sync with the OpenClaw plugin contract.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/openclaw.plugin.json

@@ -0,0 +1,130 @@
+{
+  "id": "@gralkor/openclaw",
+  "kind": "memory",
+  "name": "Gralkor Memory (OpenClaw)",
+  "description": "Persistent, temporally-aware memory via Graphiti knowledge graphs and FalkorDB",
+  "configSchema": {
+    "type": "object",
+    "required": [
+      "agentName"
+    ],
+    "properties": {
+      "agentName": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Display name for this agent. Used to label its turns in stored and recalled memory."
+      },
+      "search": {
+        "type": "object",
+        "properties": {
+          "maxResults": {
+            "type": "number",
+            "default": 20,
+            "description": "Maximum number of facts returned by the memory_search tool"
+          }
+        }
+      },
+      "llm": {
+        "type": "object",
+        "properties": {
+          "provider": {
+            "type": "string",
+            "description": "LLM provider for knowledge extraction (openai, anthropic, gemini, groq)"
+          },
+          "model": {
+            "type": "string",
+            "description": "LLM model name (e.g. gpt-4.1-mini, gemini-2.0-flash)"
+          }
+        }
+      },
+      "embedder": {
+        "type": "object",
+        "properties": {
+          "provider": {
+            "type": "string",
+            "description": "Embedding provider (openai, gemini)"
+          },
+          "model": {
+            "type": "string",
+            "description": "Embedding model name (e.g. text-embedding-3-small)"
+          }
+        }
+      },
+      "test": {
+        "type": "boolean",
+        "default": false,
+        "description": "Enable test mode — logs full episode bodies and search results for debugging"
+      },
+      "googleApiKey": {
+        "type": [
+          "string",
+          "object",
+          "null"
+        ],
+        "description": "Google API key for Gemini LLM and embeddings"
+      },
+      "openaiApiKey": {
+        "type": [
+          "string",
+          "object",
+          "null"
+        ],
+        "description": "OpenAI API key; also needed for embeddings with Anthropic/Groq providers"
+      },
+      "anthropicApiKey": {
+        "type": [
+          "string",
+          "object",
+          "null"
+        ],
+        "description": "Anthropic API key for Claude-based LLM extraction"
+      },
+      "groqApiKey": {
+        "type": [
+          "string",
+          "object",
+          "null"
+        ],
+        "description": "Groq API key for Groq-hosted LLM extraction"
+      }
+    }
+  },
+  "contracts": {
+    "tools": [
+      "memory_search",
+      "memory_add",
+      "memory_build_indices",
+      "memory_build_communities"
+    ]
+  },
+  "uiHints": {
+    "llm.provider": {
+      "label": "LLM provider"
+    },
+    "llm.model": {
+      "label": "LLM model"
+    },
+    "embedder.provider": {
+      "label": "Embedding provider"
+    },
+    "embedder.model": {
+      "label": "Embedding model"
+    },
+    "test": {
+      "label": "Test mode (verbose logging)"
+    },
+    "googleApiKey": {
+      "label": "Google API key"
+    },
+    "openaiApiKey": {
+      "label": "OpenAI API key"
+    },
+    "anthropicApiKey": {
+      "label": "Anthropic API key"
+    },
+    "groqApiKey": {
+      "label": "Groq API key"
+    }
+  },
+  "version": "4.0.0"
+}