@clawmem-ai/clawmem 0.1.8 → 0.1.10

package/src/service.ts

@@ -1,14 +1,14 @@
 // Thin orchestrator: wires conversation mirroring, memory store, and plugin lifecycle.
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
-import { isAgentConfigured, resolveAgentRoute, resolvePluginConfig } from "./config.js";
+import { hasDefaultRepo, isAgentConfigured, resolveAgentRoute, resolvePluginConfig } from "./config.js";
 import { ConversationMirror } from "./conversation.js";
 import { GitHubIssueClient } from "./github-client.js";
 import { KeyedAsyncQueue } from "./keyed-async-queue.js";
 import { MemoryStore } from "./memory.js";
 import { loadState, resolveStatePath, saveState } from "./state.js";
 import { readTranscriptSnapshot } from "./transcript.js";
-import type { ClawMemPluginConfig, PluginState, SessionMirrorState, TranscriptSnapshot } from "./types.js";
-import { inferAgentIdFromTranscriptPath, normalizeAgentId, sessionScopeKey } from "./utils.js";
+import type { BootstrapIdentityResponse, ClawMemPluginConfig, ClawMemResolvedRoute, PluginState, SessionMirrorState, TranscriptSnapshot } from "./types.js";
+import { buildAgentBootstrapRegistration, inferAgentIdFromTranscriptPath, normalizeAgentId, sessionScopeKey } from "./utils.js";
 
 type TurnPayload = { sessionId?: string; sessionKey?: string; agentId?: string; messages: unknown[] };
 type FinalizePayload = { sessionId?: string; sessionKey?: string; sessionFile?: string; agentId?: string; reason?: string; messages?: unknown[] };
@@ -30,21 +30,24 @@ class ClawMemService {
   }
 
   register(): void {
-    this.api.on("before_agent_start", async (ev, ctx) => this.handleRecall(ev.prompt, ctx.agentId));
+    this.api.on("before_agent_start", async (ev, ctx) => this.handleBeforeAgentStart(ev.prompt, ctx.agentId));
     this.api.on("agent_end", (ev, ctx) => this.scheduleTurn({ sessionId: ctx.sessionId, sessionKey: ctx.sessionKey, agentId: ctx.agentId, messages: ev.messages }));
     this.api.on("before_reset", (ev, ctx) => this.enqueueFinalize({ sessionId: ctx.sessionId, sessionKey: ctx.sessionKey, sessionFile: ev.sessionFile, agentId: ctx.agentId, reason: ev.reason, messages: ev.messages }));
     this.api.on("session_end", (ev, ctx) => this.enqueueFinalize({ sessionId: ev.sessionId ?? ctx.sessionId, sessionKey: ev.sessionKey ?? ctx.sessionKey, agentId: ctx.agentId, reason: "session_end" }));
+    this.registerTools();
 
     this.api.registerService({
       id: "clawmem",
-      start: async (ctx) => {
+      start: async (ctx: { stateDir: string }) => {
         this.statePath = resolveStatePath(ctx.stateDir);
         await this.ensureLoaded();
+        this.warnIfInactiveMemorySlot();
         this.unsubTranscript = this.api.runtime.events.onSessionTranscriptUpdate((u) => {
           void this.track(this.handleTranscript(u.sessionFile)).catch((e) => this.warn("transcript update", e));
         });
         const configuredCount = Object.keys(this.config.agents).filter((agentId) => {
-          return isAgentConfigured(resolveAgentRoute(this.config, agentId));
+          const route = resolveAgentRoute(this.config, agentId);
+          return isAgentConfigured(route) && hasDefaultRepo(route);
         }).length;
         this.api.logger.info?.(
           configuredCount > 0
@@ -61,10 +64,339 @@ class ClawMemService {
     });
   }
 
-  private async handleRecall(prompt: unknown, agentId?: string): Promise<{ prependContext: string } | void> {
-    if (typeof prompt !== "string" || prompt.trim().length < 5) return;
+  private registerTools(): void {
+    this.api.registerTool({
+      name: "memory_repos",
+      description: "List the memory repos the current ClawMem agent identity can access so the agent can choose the right space before retrieving or storing memory.",
+      required: true,
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          agentId: { type: "string", minLength: 1, description: "Optional agent identity override. Defaults to the current agent when available." },
+        },
+      },
+      execute: async (_id: string, params: unknown) => {
+        const p = asRecord(params);
+        const agentId = this.resolveToolAgentId(p.agentId);
+        const resolved = await this.requireToolIdentity(agentId);
+        if ("error" in resolved) return toolText(resolved.error);
+        const repos = await resolved.client.listUserRepos();
+        if (repos.length === 0) return toolText(`Agent "${agentId}" has no accessible ClawMem repos yet.`);
+        const lines = [
+          `Accessible ClawMem repos for agent "${agentId}":`,
+          ...repos
+            .map((repo) => {
+              const fullName = repo.full_name?.trim() || repo.name?.trim() || "unknown";
+              const flags = [
+                resolved.route.defaultRepo === fullName ? "default" : "",
+                repo.private ? "private" : "shared",
+              ].filter(Boolean).join(", ");
+              const description = repo.description?.trim() ? ` - ${repo.description.trim()}` : "";
+              return `- ${fullName}${flags ? ` [${flags}]` : ""}${description}`;
+            }),
+        ];
+        return toolText(lines.join("\n"));
+      },
+    });
+
+    this.api.registerTool({
+      name: "memory_repo_create",
+      description: "Create a new ClawMem repo under the current agent identity when the agent decides a new memory space is needed.",
+      required: true,
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          name: { type: "string", minLength: 1, description: "Repository name only, without owner prefix." },
+          description: { type: "string", minLength: 1, description: "Optional repo description." },
+          private: { type: "boolean", description: "Whether the new repo should be private. Defaults to true." },
+          setDefault: { type: "boolean", description: "Whether to make the new repo this agent's default memory repo." },
+          agentId: { type: "string", minLength: 1, description: "Optional agent identity override. Defaults to the current agent when available." },
+        },
+        required: ["name"],
+      },
+      execute: async (_id: string, params: unknown) => {
+        const p = asRecord(params);
+        const name = typeof p.name === "string" ? p.name.trim() : "";
+        if (!name) return toolText("name is empty.");
+        const agentId = this.resolveToolAgentId(p.agentId);
+        const resolved = await this.requireToolIdentity(agentId);
+        if ("error" in resolved) return toolText(resolved.error);
+        const created = await resolved.client.createUserRepo({
+          name,
+          ...(typeof p.description === "string" && p.description.trim() ? { description: p.description.trim() } : {}),
+          ...(typeof p.private === "boolean" ? { private: p.private } : {}),
+        });
+        const fullName = created.full_name?.trim() || created.name?.trim() || name;
+        let defaultNote = "";
+        const shouldSetDefault = p.setDefault === true || !resolved.route.defaultRepo;
+        if (shouldSetDefault && fullName.includes("/")) {
+          await this.persistAgentConfig(agentId, {
+            baseUrl: resolved.route.baseUrl,
+            authScheme: resolved.route.authScheme,
+            token: resolved.route.token!,
+            defaultRepo: fullName,
+          });
+          this.config.agents[agentId] = { ...(this.config.agents[agentId] ?? {}), defaultRepo: fullName };
+          defaultNote = resolved.route.defaultRepo ? "\nSet as default repo for this agent." : "\nSet as the first default repo for this agent.";
+        }
+        return toolText(`Created memory repo ${fullName}.${defaultNote}`);
+      },
+    });
+
+    this.api.registerTool({
+      name: "memory_list",
+      description: "List ClawMem memories by status or schema so the agent can inspect the current memory index before deduping or saving.",
+      required: true,
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          status: { type: "string", enum: ["active", "stale", "all"], description: "Which memories to list. Defaults to active." },
+          kind: { type: "string", minLength: 1, description: "Optional kind filter, for example core-fact, lesson, or task." },
+          topic: { type: "string", minLength: 1, description: "Optional topic filter." },
+          limit: { type: "integer", minimum: 1, maximum: 200, description: "Maximum number of memories to return." },
+          repo: { type: "string", minLength: 3, description: "Optional memory repo override in owner/repo form. Defaults to the agent's defaultRepo." },
+          agentId: { type: "string", minLength: 1, description: "Optional agent route override. Defaults to the current agent when available." },
+        },
+      },
+      execute: async (_id: string, params: unknown) => {
+        const p = asRecord(params);
+        const agentId = this.resolveToolAgentId(p.agentId);
+        const resolved = await this.requireToolRoute(agentId, p.repo);
+        if ("error" in resolved) return toolText(resolved.error);
+        const status = p.status === "stale" || p.status === "all" ? p.status : "active";
+        const limit = typeof p.limit === "number" && Number.isFinite(p.limit) ? Math.floor(p.limit) : 20;
+        const kind = typeof p.kind === "string" && p.kind.trim() ? p.kind.trim() : undefined;
+        const topic = typeof p.topic === "string" && p.topic.trim() ? p.topic.trim() : undefined;
+        const memories = await resolved.mem.listMemories({ status, kind, topic, limit });
+        if (memories.length === 0) {
+          const filters = [status !== "active" ? `status=${status}` : "", kind ? `kind=${kind}` : "", topic ? `topic=${topic}` : ""].filter(Boolean).join(", ");
+          return toolText(`No memories matched in ${resolved.route.repo}${filters ? ` (${filters})` : ""}.`);
+        }
+        const lines = [
+          `Found ${memories.length} ${status === "all" ? "" : `${status} `}memor${memories.length === 1 ? "y" : "ies"} in ${resolved.route.repo}:`,
+          ...memories.map((memory) => `- ${renderMemoryLine(memory)}`),
+        ];
+        return toolText(lines.join("\n"));
+      },
+    });
+
+    this.api.registerTool({
+      name: "memory_labels",
+      description: "List existing ClawMem schema labels so the agent can reuse current kinds and topics before adding new ones.",
+      required: true,
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          repo: { type: "string", minLength: 3, description: "Optional memory repo override in owner/repo form. Defaults to the agent's defaultRepo." },
+          agentId: { type: "string", minLength: 1, description: "Optional agent route override. Defaults to the current agent when available." },
+          limitTopics: { type: "integer", minimum: 1, maximum: 200, description: "Maximum number of topic labels to display." },
+        },
+      },
+      execute: async (_id: string, params: unknown) => {
+        const p = asRecord(params);
+        const agentId = this.resolveToolAgentId(p.agentId);
+        const resolved = await this.requireToolRoute(agentId, p.repo);
+        if ("error" in resolved) return toolText(resolved.error);
+        const schema = await resolved.mem.listSchema();
+        const rawLimit = typeof p.limitTopics === "number" && Number.isFinite(p.limitTopics) ? Math.floor(p.limitTopics) : 50;
+        const limitTopics = Math.min(200, Math.max(1, rawLimit));
+        const kinds = schema.kinds.length > 0 ? schema.kinds.map((kind) => `- kind:${kind}`).join("\n") : "- None";
+        const topics = schema.topics.length > 0 ? schema.topics.slice(0, limitTopics).map((topic) => `- topic:${topic}`).join("\n") : "- None";
+        const extra = schema.topics.length > limitTopics ? `\n- ...and ${schema.topics.length - limitTopics} more topics` : "";
+        return toolText([
+          `Current ClawMem schema labels in ${resolved.route.repo}:`,
+          "",
+          "Kinds:",
+          kinds,
+          "",
+          "Topics:",
+          `${topics}${extra}`,
+        ].join("\n"));
+      },
+    });
+
+    this.api.registerTool({
+      name: "memory_recall",
+      description: "Search ClawMem active memories for relevant prior facts, decisions, conventions, and lessons.",
+      required: true,
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          query: { type: "string", minLength: 1, description: "What to recall from memory." },
+          limit: { type: "integer", minimum: 1, maximum: 20, description: "Maximum number of memories to return." },
+          repo: { type: "string", minLength: 3, description: "Optional memory repo override in owner/repo form. Defaults to the agent's defaultRepo." },
+          agentId: { type: "string", minLength: 1, description: "Optional agent route override. Defaults to the current agent when available." },
+        },
+        required: ["query"],
+      },
+      execute: async (_id: string, params: unknown) => {
+        const p = asRecord(params);
+        const query = typeof p.query === "string" ? p.query.trim() : "";
+        if (!query) return toolText("Query is empty.");
+        const agentId = this.resolveToolAgentId(p.agentId);
+        const resolved = await this.requireToolRoute(agentId, p.repo);
+        if ("error" in resolved) return toolText(resolved.error);
+        const rawLimit = typeof p.limit === "number" && Number.isFinite(p.limit) ? Math.floor(p.limit) : this.config.memoryRecallLimit;
+        const limit = Math.min(20, Math.max(1, rawLimit));
+        const memories = await resolved.mem.search(query, limit);
+        if (memories.length === 0) return toolText(`No active memories matched "${query}" in ${resolved.route.repo}.`);
+        const text = [
+          `Found ${memories.length} active memor${memories.length === 1 ? "y" : "ies"} for "${query}" in ${resolved.route.repo}:`,
+          ...memories.map((memory) => `- ${renderMemoryLine(memory)}`),
+        ].join("\n");
+        return toolText(text);
+      },
+    });
+
+    this.api.registerTool({
+      name: "memory_get",
+      description: "Fetch one ClawMem memory by memory id or issue number so the agent can verify an exact record.",
+      required: true,
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          memoryId: { type: "string", minLength: 1, description: "The memory id or issue number to retrieve." },
+          status: { type: "string", enum: ["active", "stale", "all"], description: "Which status bucket to search. Defaults to all." },
+          repo: { type: "string", minLength: 3, description: "Optional memory repo override in owner/repo form. Defaults to the agent's defaultRepo." },
+          agentId: { type: "string", minLength: 1, description: "Optional agent route override. Defaults to the current agent when available." },
+        },
+        required: ["memoryId"],
+      },
+      execute: async (_id: string, params: unknown) => {
+        const p = asRecord(params);
+        const memoryId = typeof p.memoryId === "string" ? p.memoryId.trim() : "";
+        if (!memoryId) return toolText("memoryId is empty.");
+        const agentId = this.resolveToolAgentId(p.agentId);
+        const resolved = await this.requireToolRoute(agentId, p.repo);
+        if ("error" in resolved) return toolText(resolved.error);
+        const status = p.status === "active" || p.status === "stale" ? p.status : "all";
+        const memory = await resolved.mem.get(memoryId, status);
+        if (!memory) return toolText(`No ${status === "all" ? "" : `${status} `}memory matched id "${memoryId}" in ${resolved.route.repo}.`);
+        return toolText(`Repo: ${resolved.route.repo}\n${renderMemoryBlock(memory)}`);
+      },
+    });
+
+    this.api.registerTool({
+      name: "memory_store",
+      description: "Store a durable ClawMem memory immediately instead of waiting for session finalization.",
+      required: true,
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          detail: { type: "string", minLength: 1, description: "The durable fact, lesson, decision, or preference to remember." },
+          kind: { type: "string", minLength: 1, description: "Optional schema kind, for example lesson, convention, skill, or task." },
+          topics: {
+            type: "array",
+            description: "Optional topic labels to improve future retrieval.",
+            items: { type: "string", minLength: 1 },
+            minItems: 1,
+            maxItems: 10,
+          },
+          repo: { type: "string", minLength: 3, description: "Optional memory repo override in owner/repo form. Defaults to the agent's defaultRepo." },
+          agentId: { type: "string", minLength: 1, description: "Optional agent route override. Defaults to the current agent when available." },
+        },
+        required: ["detail"],
+      },
+      execute: async (_id: string, params: unknown) => {
+        const p = asRecord(params);
+        const detail = typeof p.detail === "string" ? p.detail.trim() : "";
+        if (!detail) return toolText("Detail is empty.");
+        const agentId = this.resolveToolAgentId(p.agentId);
+        const resolved = await this.requireToolRoute(agentId, p.repo);
+        if ("error" in resolved) return toolText(resolved.error);
+        const kind = typeof p.kind === "string" && p.kind.trim() ? p.kind.trim() : undefined;
+        const topics = Array.isArray(p.topics) ? p.topics.filter((topic): topic is string => typeof topic === "string" && topic.trim().length > 0) : undefined;
+        const result = await resolved.mem.store({ detail, ...(kind ? { kind } : {}), ...(topics && topics.length > 0 ? { topics } : {}) });
+        if (!result.created) return toolText(`Memory already exists in ${resolved.route.repo}.\n${renderMemoryBlock(result.memory)}`);
+        return toolText(`Stored memory in ${resolved.route.repo}.\n${renderMemoryBlock(result.memory)}`);
+      },
+    });
+
+    this.api.registerTool({
+      name: "memory_update",
+      description: "Update an existing ClawMem memory in place when the same canonical fact or task has evolved.",
+      required: true,
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          memoryId: { type: "string", minLength: 1, description: "The memory id or issue number to update." },
+          detail: { type: "string", minLength: 1, description: "Optional replacement detail text for the same memory record." },
+          kind: { type: "string", minLength: 1, description: "Optional replacement kind label." },
+          topics: {
+            type: "array",
+            description: "Optional replacement topic labels.",
+            items: { type: "string", minLength: 1 },
+            minItems: 1,
+            maxItems: 10,
+          },
+          repo: { type: "string", minLength: 3, description: "Optional memory repo override in owner/repo form. Defaults to the agent's defaultRepo." },
+          agentId: { type: "string", minLength: 1, description: "Optional agent route override. Defaults to the current agent when available." },
+        },
+        required: ["memoryId"],
+      },
+      execute: async (_id: string, params: unknown) => {
+        const p = asRecord(params);
+        const memoryId = typeof p.memoryId === "string" ? p.memoryId.trim() : "";
+        if (!memoryId) return toolText("memoryId is empty.");
+        const detail = typeof p.detail === "string" && p.detail.trim() ? p.detail.trim() : undefined;
+        const kind = typeof p.kind === "string" && p.kind.trim() ? p.kind.trim() : undefined;
+        const topics = Array.isArray(p.topics) ? p.topics.filter((topic): topic is string => typeof topic === "string" && topic.trim().length > 0) : undefined;
+        if (!detail && kind === undefined && topics === undefined) return toolText("Provide at least one of detail, kind, or topics.");
+        const agentId = this.resolveToolAgentId(p.agentId);
+        const resolved = await this.requireToolRoute(agentId, p.repo);
+        if ("error" in resolved) return toolText(resolved.error);
+        let updated;
+        try {
+          updated = await resolved.mem.update(memoryId, { ...(detail ? { detail } : {}), ...(kind !== undefined ? { kind } : {}), ...(topics !== undefined ? { topics } : {}) });
+        } catch (error) {
+          return toolText(`Unable to update memory "${memoryId}": ${String(error)}`);
+        }
+        if (!updated) return toolText(`No memory matched id "${memoryId}" in ${resolved.route.repo}.`);
+        return toolText(`Updated memory in ${resolved.route.repo}.\n${renderMemoryBlock(updated)}`);
+      },
+    });
+
+    this.api.registerTool({
+      name: "memory_forget",
+      description: "Mark an active ClawMem memory as stale when it is superseded or no longer true.",
+      required: true,
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          memoryId: { type: "string", minLength: 1, description: "The memory id or issue number to mark stale." },
+          repo: { type: "string", minLength: 3, description: "Optional memory repo override in owner/repo form. Defaults to the agent's defaultRepo." },
+          agentId: { type: "string", minLength: 1, description: "Optional agent route override. Defaults to the current agent when available." },
+        },
+        required: ["memoryId"],
+      },
+      execute: async (_id: string, params: unknown) => {
+        const p = asRecord(params);
+        const memoryId = typeof p.memoryId === "string" ? p.memoryId.trim() : "";
+        if (!memoryId) return toolText("memoryId is empty.");
+        const agentId = this.resolveToolAgentId(p.agentId);
+        const resolved = await this.requireToolRoute(agentId, p.repo);
+        if ("error" in resolved) return toolText(resolved.error);
+        const forgotten = await resolved.mem.forget(memoryId);
+        if (!forgotten) return toolText(`No active memory matched id "${memoryId}" in ${resolved.route.repo}.`);
+        return toolText(`Marked memory [${forgotten.memoryId}] stale in ${resolved.route.repo}: ${forgotten.detail}`);
+      },
+    });
+  }
+
+  private async handleBeforeAgentStart(prompt: unknown, agentId?: string): Promise<{ prependContext: string } | void> {
     const routeAgentId = normalizeAgentId(agentId);
-    if (!(await this.ensureConfigured(routeAgentId))) return;
+    if (!(await this.ensureDefaultRepoConfigured(routeAgentId))) return;
+    await this.runRequestMaintenance(routeAgentId);
+    if (typeof prompt !== "string" || prompt.trim().length < 5) return;
     try {
       const { mem } = this.getServices(routeAgentId);
       const memories = await mem.search(prompt, this.config.memoryRecallLimit);
@@ -87,7 +419,7 @@ class ClawMemService {
     }
     const { conv } = this.getServices(agentId);
     if (!conv.shouldMirror(snap.sessionId, snap.messages)) return;
-    if (!(await this.ensureConfigured(agentId))) return;
+    if (!(await this.ensureDefaultRepoConfigured(agentId))) return;
     await this.enqueueSession(sessionScopeKey(snap.sessionId, agentId), async () => {
       const s = this.getOrCreate(snap.sessionId!, agentId);
       s.sessionFile = sessionFile;
@@ -113,7 +445,7 @@ class ClawMemService {
   private async syncTurn(p: TurnPayload): Promise<void> {
     if (!p.sessionId) return;
     const agentId = normalizeAgentId(p.agentId);
-    if (!(await this.ensureConfigured(agentId))) return;
+    if (!(await this.ensureDefaultRepoConfigured(agentId))) return;
     const { conv } = this.getServices(agentId);
     const s = this.getOrCreate(p.sessionId, agentId);
     s.sessionKey = p.sessionKey ?? s.sessionKey; s.agentId = agentId; s.updatedAt = new Date().toISOString();
@@ -137,8 +469,8 @@ class ClawMemService {
   private async finalize(p: FinalizePayload): Promise<void> {
     if (!p.sessionId) return;
     const agentId = normalizeAgentId(p.agentId);
-    if (!(await this.ensureConfigured(agentId))) return;
-    const { conv, mem } = this.getServices(agentId);
+    if (!(await this.ensureDefaultRepoConfigured(agentId))) return;
+    const { conv } = this.getServices(agentId);
     const s = this.getOrCreate(p.sessionId, agentId);
     if (s.finalizedAt) return;
     s.sessionKey = p.sessionKey ?? s.sessionKey; s.sessionFile = p.sessionFile ?? s.sessionFile;
@@ -150,21 +482,11 @@ class ClawMemService {
     const next = snap.messages.slice(s.lastMirroredCount);
     let allOk = true;
     if (next.length > 0) { const n = await conv.appendComments(s.issueNumber!, next); s.lastMirroredCount += n; s.turnCount += n; allOk = n === next.length; }
-    let summary = "pending";
-    let generatedTitle: string | undefined;
-    try {
-      const result = await conv.generateSummaryAndTitle(s, snap);
-      summary = result.summary;
-      generatedTitle = result.title;
-    } catch (e) { summary = `failed: ${String(e)}`; }
     await conv.syncLabels(s, snap, true);
-    await conv.syncBody(s, snap, summary, true, generatedTitle);
-    await mem.syncFromConversation(s, snap);
+    await conv.syncBody(s, snap, "pending", true);
+    s.summaryStatus = "pending";
     if (allOk) s.finalizedAt = new Date().toISOString();
     await this.persistState();
-
-    // Auto-name the repo if it still has no description (first few conversations).
-    this.maybeAutoNameRepo(agentId, summary, generatedTitle);
   }
 
   // --- Infrastructure ---
@@ -220,7 +542,7 @@ class ClawMemService {
     })();
     return this.loadPromise;
   }
-  private async ensureConfigured(agentId?: string): Promise<boolean> {
+  private async ensureIdentityConfigured(agentId?: string): Promise<boolean> {
     const id = normalizeAgentId(agentId);
     if (isAgentConfigured(resolveAgentRoute(this.config, id))) return true;
     const pending = this.configPromises.get(id);
@@ -229,20 +551,72 @@ class ClawMemService {
     this.configPromises.set(id, p);
     try { return await p; } finally { if (this.configPromises.get(id) === p) this.configPromises.delete(id); }
   }
+  private async ensureDefaultRepoConfigured(agentId?: string): Promise<boolean> {
+    const id = normalizeAgentId(agentId);
+    if (!(await this.ensureIdentityConfigured(id))) return false;
+    return hasDefaultRepo(resolveAgentRoute(this.config, id));
+  }
   private async bootstrap(agentId: string): Promise<boolean> {
     const route = resolveAgentRoute(this.config, agentId);
     if (!route.baseUrl) { this.api.logger.warn(`clawmem: cannot provision Git credentials for ${agentId} without a baseUrl`); return false; }
     try {
       const client = new GitHubIssueClient(route, this.api.logger);
-      const locale = Intl?.DateTimeFormat?.()?.resolvedOptions?.()?.locale ?? "";
-      const sess = await client.createAnonymousSession(locale);
-      await this.persistAgentConfig(agentId, { baseUrl: route.baseUrl, authScheme: "token", token: sess.token, repo: sess.repo_full_name });
-      this.config.agents[agentId] = { ...(this.config.agents[agentId] ?? {}), baseUrl: route.baseUrl, authScheme: "token", token: sess.token, repo: sess.repo_full_name };
-      this.api.logger.info?.(`clawmem: provisioned Git credentials for agent ${agentId} -> ${sess.repo_full_name} via ${route.baseUrl}`);
+      const bootstrap = await this.provisionAgentIdentity(client, agentId);
+      await this.persistAgentConfig(agentId, {
+        baseUrl: route.baseUrl,
+        authScheme: "token",
+        token: bootstrap.identity.token,
+        defaultRepo: bootstrap.identity.repo_full_name,
+      });
+      this.config.agents[agentId] = {
+        ...(this.config.agents[agentId] ?? {}),
+        baseUrl: route.baseUrl,
+        authScheme: "token",
+        token: bootstrap.identity.token,
+        defaultRepo: bootstrap.identity.repo_full_name,
+      };
+      this.api.logger.info?.(
+        `clawmem: provisioned Git credentials for agent ${agentId} with default repo ${bootstrap.identity.repo_full_name} via ${route.baseUrl} (${bootstrap.method})`,
+      );
       return true;
     } catch (error) { this.api.logger.warn(`clawmem: failed to provision Git credentials for agent ${agentId} via ${route.baseUrl}: ${String(error)}`); return false; }
   }
-  private async persistAgentConfig(agentId: string, values: { baseUrl: string; authScheme: "token" | "bearer"; token: string; repo: string }): Promise<void> {
+  private async provisionAgentIdentity(client: GitHubIssueClient, agentId: string): Promise<{ identity: BootstrapIdentityResponse; method: string }> {
+    const registration = buildAgentBootstrapRegistration(agentId);
+    try {
+      const identity = await client.registerAgent(registration.prefixLogin, registration.defaultRepoName);
+      return { identity, method: "/api/v3/agents" };
+    } catch (error) {
+      if (!shouldFallbackToAnonymousBootstrap(error)) throw error;
+      this.api.logger.warn?.(`clawmem: /api/v3/agents is unavailable for agent ${agentId}; falling back to deprecated anonymous bootstrap`);
+    }
+
+    const locale = Intl?.DateTimeFormat?.()?.resolvedOptions?.()?.locale ?? "";
+    const identity = await client.createAnonymousSession(locale);
+    return { identity, method: "/api/v3/anonymous/session" };
+  }
+  private warnIfInactiveMemorySlot(): void {
+    try {
+      const root = this.api.runtime.config.loadConfig();
+      const plugins = asRecord(root.plugins);
+      const slots = asRecord(plugins.slots);
+      const slot = typeof slots.memory === "string" ? String(slots.memory).trim() : "";
+      if (!slot) {
+        this.api.logger.warn(
+          `clawmem: plugins.slots.memory is not set, so OpenClaw may keep the default memory plugin active. Set plugins.slots.memory to "${this.api.id}" and restart the gateway.`,
+        );
+        return;
+      }
+      if (slot !== this.api.id) {
+        this.api.logger.warn(
+          `clawmem: plugins.slots.memory is "${slot}", so ClawMem is not the selected memory plugin. Set plugins.slots.memory to "${this.api.id}" and restart the gateway.`,
+        );
+      }
+    } catch (error) {
+      this.api.logger.warn(`clawmem: memory slot check failed: ${String(error)}`);
+    }
+  }
+  private async persistAgentConfig(agentId: string, values: { baseUrl: string; authScheme: "token" | "bearer"; token: string; defaultRepo: string }): Promise<void> {
     const root = this.api.runtime.config.loadConfig();
     const plugins = root.plugins;
     const entries = plugins?.entries && typeof plugins.entries === "object" && !Array.isArray(plugins.entries) ? (plugins.entries as Record<string, unknown>) : {};
@@ -269,13 +643,98 @@ class ClawMemService {
       },
     });
   }
-  private getServices(agentId?: string): { conv: ConversationMirror; mem: MemoryStore } {
-    const client = new GitHubIssueClient(resolveAgentRoute(this.config, agentId), this.api.logger);
+  private async runRequestMaintenance(agentId: string): Promise<void> {
+    const sessions = Object.values(this.state.sessions)
+      .filter((session) => normalizeAgentId(session.agentId) === agentId)
+      .sort((a, b) => Date.parse(b.updatedAt ?? b.createdAt ?? "") - Date.parse(a.updatedAt ?? a.createdAt ?? ""))
+      .slice(0, 8);
+    if (sessions.length === 0) return;
+    const { conv, mem } = this.getServices(agentId);
+    let changed = false;
+    let workDone = 0;
+    for (const session of sessions) {
+      if (workDone >= 3) break;
+      const snap = await conv.loadSnapshot(session, []);
+      if (!conv.shouldMirror(session.sessionId, snap.messages) || snap.messages.length === 0) continue;
+      if (!session.issueNumber) {
+        await conv.ensureIssue(session, snap);
+        changed = true;
+      }
+      if (session.summaryStatus === "pending") {
+        try {
+          const result = await conv.generateSummaryAndTitle(session, snap);
+          await conv.syncLabels(session, snap, true);
+          await conv.syncBody(session, snap, result.summary, true, result.title);
+          session.summaryStatus = "complete";
+          if (result.title?.trim()) {
+            session.issueTitle = result.title.trim();
+            session.titleSource = "llm";
+          }
+          this.maybeAutoNameRepo(agentId, result.summary, result.title);
+          changed = true;
+          workDone++;
+        } catch (error) {
+          this.warn(`request-scoped summary sync for ${session.sessionId}`, error);
+        }
+      }
+      if (session.titleSource !== "llm" && snap.messages.length >= 2) {
+        await conv.syncTitle(session, snap);
+        changed = true;
+        workDone++;
+      }
+      if (snap.messages.length >= 2 && snap.messages.length > (session.lastMemorySyncCount ?? 0)) {
+        const ok = await mem.syncFromConversation(session, snap);
+        if (ok) {
+          session.lastMemorySyncCount = snap.messages.length;
+          changed = true;
+        }
+        workDone++;
+      }
+    }
+    if (changed) await this.persistState();
+  }
+
+  private getServices(agentId?: string, repo?: string): { route: ClawMemResolvedRoute; conv: ConversationMirror; mem: MemoryStore; client: GitHubIssueClient } {
+    const route = resolveAgentRoute(this.config, agentId, repo);
+    const client = new GitHubIssueClient(route, this.api.logger);
     return {
+      route,
+      client,
       conv: new ConversationMirror(client, this.api, this.config),
       mem: new MemoryStore(client, this.api, this.config),
     };
   }
+  private resolveToolAgentId(agentId: unknown): string {
+    return normalizeAgentId(typeof agentId === "string" && agentId.trim() ? agentId : process.env.OPENCLAW_AGENT_ID);
+  }
+  private resolveToolRepo(repo: unknown): { repo?: string; error?: string } {
+    if (repo === undefined || repo === null || repo === "") return {};
+    if (typeof repo !== "string") return { error: "repo must be a string like owner/repo." };
+    const trimmed = repo.trim().replace(/^\/+|\/+$/g, "");
+    if (!/^[^/\s]+\/[^/\s]+$/.test(trimmed)) return { error: `Invalid repo "${repo}". Expected owner/repo.` };
+    return { repo: trimmed };
+  }
+  private async requireToolIdentity(agentId: string): Promise<{ route: ClawMemResolvedRoute; client: GitHubIssueClient } | { error: string }> {
+    if (!(await this.ensureIdentityConfigured(agentId))) {
+      return { error: `ClawMem identity for agent "${agentId}" is not configured.` };
+    }
+    const { route, client } = this.getServices(agentId);
+    return { route, client };
+  }
+  private async requireToolRoute(agentId: string, repo: unknown): Promise<{ route: ClawMemResolvedRoute; conv: ConversationMirror; mem: MemoryStore; client: GitHubIssueClient } | { error: string }> {
+    const parsed = this.resolveToolRepo(repo);
+    if (parsed.error) return { error: parsed.error };
+    if (!(await this.ensureIdentityConfigured(agentId))) {
+      return { error: `ClawMem identity for agent "${agentId}" is not configured.` };
+    }
+    const services = this.getServices(agentId, parsed.repo);
+    if (!services.route.repo) {
+      return {
+        error: `No memory repo selected for agent "${agentId}". Provide repo explicitly or configure agents.${agentId}.defaultRepo.`,
+      };
+    }
+    return services;
+  }
   /**
    * After finalization, check if the repo still has an empty/default description.
    * If so, use the conversation summary to suggest a meaningful name and update
@@ -302,5 +761,29 @@ class ClawMemService {
 }
 
 function asRecord(v: unknown): Record<string, unknown> { return v && typeof v === "object" ? (v as Record<string, unknown>) : {}; }
+function shouldFallbackToAnonymousBootstrap(error: unknown): boolean {
+  const msg = String(error);
+  return /^Error:\s*HTTP (404|405|501):/i.test(msg) || /^HTTP (404|405|501):/i.test(msg);
+}
+function toolText(text: string): { content: Array<{ type: "text"; text: string }> } {
+  return { content: [{ type: "text", text }] };
+}
+function renderMemoryLine(memory: { memoryId: string; title?: string; detail: string; kind?: string; topics?: string[]; status: "active" | "stale" }): string {
+  const schema = [memory.kind ? `kind:${memory.kind}` : "", ...(memory.topics ?? []).map((topic) => `topic:${topic}`)].filter(Boolean).join(", ");
+  return `[${memory.memoryId}] ${memory.title || "Memory"}${schema ? ` (${schema})` : ""}${memory.status === "stale" ? " [stale]" : ""}: ${memory.detail}`;
+}
+function renderMemoryBlock(memory: { memoryId: string; issueNumber?: number; title?: string; detail: string; kind?: string; topics?: string[]; status: "active" | "stale"; date?: string }): string {
+  const lines = [
+    `Memory ID: ${memory.memoryId}`,
+    ...(typeof memory.issueNumber === "number" ? [`Issue Number: ${memory.issueNumber}`] : []),
+    `Status: ${memory.status}`,
+    `Title: ${memory.title || "Memory"}`,
+    ...(memory.kind ? [`Kind: ${memory.kind}`] : []),
+    ...(memory.topics && memory.topics.length > 0 ? [`Topics: ${memory.topics.join(", ")}`] : []),
+    ...(memory.date ? [`Date: ${memory.date}`] : []),
+    `Detail: ${memory.detail}`,
+  ];
+  return lines.join("\n");
+}
 
 export function createClawMemPlugin(api: OpenClawPluginApi): void { new ClawMemService(api).register(); }