@clawmem-ai/clawmem 0.1.3

package/src/conversation.ts

@@ -0,0 +1,162 @@
+// Session mirroring: creates/updates GitHub issues and comments for each conversation.
+import fs from "node:fs";
+import path from "node:path";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { AGENT_LABEL_PREFIX, DEFAULT_LABELS, LABEL_ACTIVE, LABEL_CLOSED, SESSION_TITLE_PREFIX } from "./config.js";
+import type { GitHubIssueClient } from "./github-client.js";
+import { normalizeMessages, readTranscriptSnapshot } from "./transcript.js";
+import type { ClawMemPluginConfig, NormalizedMessage, SessionMirrorState, TranscriptSnapshot } from "./types.js";
+import { fmtTranscript, localDate, localDateTime, sha256, subKey } from "./utils.js";
+import { stringifyFlatYaml } from "./yaml.js";
+
+export class ConversationMirror {
+  constructor(private readonly client: GitHubIssueClient, private readonly api: OpenClawPluginApi, private readonly config: ClawMemPluginConfig) {}
+
+  shouldMirror(sessionId: string, messages: NormalizedMessage[]): boolean {
+    if (sessionId.startsWith("slug-generator-")) return false;
+    const first = messages.find((m) => m.role === "user")?.text ?? "";
+    if (first.includes("generate a short 1-2 word filename slug") && first.includes("Reply with ONLY the slug")) return false;
+    if (first.includes("Summarize the following conversation.") && first.includes('Return valid JSON only in the form {"summary":"..."}')) return false;
+    if (first.includes("Extract durable memories from the conversation below.") && first.includes('Return JSON only in the form {"save":')) return false;
+    return true;
+  }
+
+  async loadSnapshot(session: SessionMirrorState, fallback: unknown[]): Promise<TranscriptSnapshot> {
+    const filePath = await this.resolveTranscriptPath(session.sessionFile);
+    if (filePath) {
+      session.sessionFile = filePath;
+      try {
+        const t = await readTranscriptSnapshot(filePath);
+        return { sessionId: t.sessionId ?? session.sessionId, messages: t.messages };
+      } catch (error) {
+        this.api.logger.warn(`clawmem: transcript read failed for ${filePath}: ${String(error)}`);
+      }
+    }
+    return { sessionId: session.sessionId, messages: normalizeMessages(fallback) };
+  }
+
+  async ensureIssue(session: SessionMirrorState, snapshot: TranscriptSnapshot): Promise<void> {
+    if (session.issueNumber) return;
+    const title = `${SESSION_TITLE_PREFIX}${session.sessionId}`;
+    const labels = this.buildLabels(session, snapshot, false);
+    const body = this.renderBody(session, snapshot, "pending", false);
+    await this.client.ensureLabels(labels);
+    const issue = await this.client.createIssue({ title, body, labels });
+    session.issueNumber = issue.number;
+    session.issueTitle = issue.title ?? title;
+    session.lastSummaryHash = sha256(`${title}\n${body}\nopen`);
+    session.createdAt = new Date().toISOString();
+    session.updatedAt = session.createdAt;
+  }
+
+  async syncBody(session: SessionMirrorState, snapshot: TranscriptSnapshot, summary: string, closed: boolean): Promise<void> {
+    if (!session.issueNumber) return;
+    const title = `${SESSION_TITLE_PREFIX}${session.sessionId}`;
+    const body = this.renderBody(session, snapshot, summary, closed);
+    const hash = sha256(`${title}\n${body}\n${closed ? "closed" : "open"}`);
+    if (hash === session.lastSummaryHash) return;
+    await this.client.updateIssue(session.issueNumber, { title, body, ...(closed ? { state: "closed" as const } : {}) });
+    session.issueTitle = title;
+    session.lastSummaryHash = hash;
+  }
+
+  async syncLabels(session: SessionMirrorState, snapshot: TranscriptSnapshot, closed: boolean): Promise<void> {
+    if (!session.issueNumber) return;
+    const labels = this.buildLabels(session, snapshot, closed);
+    await this.client.ensureLabels(labels);
+    await this.client.syncManagedLabels(session.issueNumber, labels);
+  }
+
+  async appendComments(issueNumber: number, messages: NormalizedMessage[]): Promise<number> {
+    let count = 0;
+    for (const msg of messages) {
+      try { await this.client.createComment(issueNumber, `role: ${msg.role}\n\n${msg.text.trim()}`); count++; }
+      catch (error) { this.api.logger.warn(`clawmem: conversation comment failed: ${String(error)}`); break; }
+    }
+    return count;
+  }
+
+  async generateSummary(session: SessionMirrorState, snapshot: TranscriptSnapshot): Promise<string> {
+    if (snapshot.messages.length === 0) throw new Error("no conversation messages to summarize");
+    const subagent = this.api.runtime.subagent;
+    const sessionKey = subKey(session, "summary");
+    const message = [
+      "Summarize the following conversation.",
+      'Return valid JSON only in the form {"summary":"..."}',
+      "The summary should be concise, factual, and written in 2-4 sentences.",
+      "Do not include markdown, bullet points, or analysis.",
+      "", "<conversation>", fmtTranscript(snapshot.messages), "</conversation>",
+    ].join("\n");
+    try {
+      const run = await subagent.run({
+        sessionKey, message, deliver: false, lane: "clawmem-summary",
+        idempotencyKey: sha256(`${session.sessionId}:${snapshot.messages.length}:summary`),
+        extraSystemPrompt: "You summarize OpenClaw conversations. Output JSON only with one string field named summary.",
+      });
+      const wait = await subagent.waitForRun({ runId: run.runId, timeoutMs: this.config.summaryWaitTimeoutMs });
+      if (wait.status === "timeout") throw new Error("summary subagent timed out");
+      if (wait.status === "error") throw new Error(wait.error || "summary subagent failed");
+      const msgs = normalizeMessages((await subagent.getSessionMessages({ sessionKey, limit: 50 })).messages);
+      const text = [...msgs].reverse().find((e) => e.role === "assistant" && e.text.trim())?.text;
+      if (!text) throw new Error("summary subagent returned no assistant text");
+      return parseSummary(text);
+    } finally { subagent.deleteSession({ sessionKey, deleteTranscript: true }).catch(() => {}); }
+  }
+
+  private buildLabels(session: SessionMirrorState, snapshot: TranscriptSnapshot, closed: boolean): string[] {
+    const dates = this.resolveDates(session, snapshot.messages);
+    const labels = new Set([...DEFAULT_LABELS, "type:conversation", `session:${session.sessionId}`, `date:${dates.date}`]);
+    if (session.agentId) labels.add(`${AGENT_LABEL_PREFIX}${session.agentId}`);
+    labels.add(closed ? LABEL_CLOSED : LABEL_ACTIVE);
+    return [...labels].filter((l) => l.trim().length > 0);
+  }
+
+  private renderBody(session: SessionMirrorState, snapshot: TranscriptSnapshot, summary: string, closed: boolean): string {
+    const dates = this.resolveDates(session, snapshot.messages);
+    return stringifyFlatYaml([
+      ["type", "conversation"], ["session_id", session.sessionId], ["date", dates.date],
+      ["start_at", dates.startAt], ["end_at", dates.endAt],
+      ["status", closed ? "closed" : "active"], ["summary", summary],
+    ]);
+  }
+
+  private resolveDates(session: SessionMirrorState, messages: NormalizedMessage[]): { date: string; startAt: string; endAt: string } {
+    const ts = messages.map((m) => m.timestamp).filter((v): v is string => Boolean(v?.trim()))
+      .map((v) => new Date(v)).filter((d) => Number.isFinite(d.getTime()));
+    const fallbackStart = session.createdAt ? new Date(session.createdAt) : new Date();
+    const fallbackEnd = session.updatedAt ? new Date(session.updatedAt) : fallbackStart;
+    const start = ts[0] ?? fallbackStart, end = ts.at(-1) ?? fallbackEnd;
+    return { date: localDate(start), startAt: localDateTime(start), endAt: localDateTime(end) };
+  }
+
+  private async resolveTranscriptPath(filePath: string | undefined): Promise<string | null> {
+    if (!filePath) return null;
+    if (await fexists(filePath)) return filePath;
+    try {
+      const dir = path.dirname(filePath), prefix = `${path.basename(filePath)}.reset.`;
+      const latest = (await fs.promises.readdir(dir, { withFileTypes: true }))
+        .filter((e) => e.isFile() && e.name.startsWith(prefix)).map((e) => e.name).sort().at(-1);
+      if (latest) {
+        this.api.logger.info?.(`clawmem: using reset transcript ${path.join(dir, latest)} because ${filePath} is missing`);
+        return path.join(dir, latest);
+      }
+    } catch { /* directory unreadable */ }
+    return null;
+  }
+}
+
+async function fexists(p: string): Promise<boolean> { try { return (await fs.promises.stat(p)).isFile(); } catch { return false; } }
+function parseSummary(raw: string): string {
+  const tryParse = (s: string): string | null => {
+    try { const p = JSON.parse(s) as { summary?: unknown }; return typeof p?.summary === "string" && p.summary.trim() ? p.summary.trim() : null; }
+    catch { const i = s.indexOf("{"), j = s.lastIndexOf("}");
+      if (i >= 0 && j > i) { try { const p = JSON.parse(s.slice(i, j + 1)) as { summary?: unknown }; return typeof p?.summary === "string" && p.summary.trim() ? p.summary.trim() : null; } catch { return null; } }
+      return null;
+    }
+  };
+  const t = raw.trim();
+  const direct = tryParse(t); if (direct) return direct;
+  const f = /^```(?:json)?\s*([\s\S]*?)```$/i.exec(t);
+  if (f?.[1]) { const nested = tryParse(f[1].trim()); if (nested) return nested; }
+  return t;
+}

package/src/github-client.ts

@@ -0,0 +1,64 @@
+// GitHub Issues API client for clawmem. No label caching — idempotent create-if-absent.
+import { resolveLabelColor, labelDescription, extractLabelNames, isManagedLabel } from "./config.js";
+import type { AnonymousSessionResponse, ClawMemPluginConfig } from "./types.js";
+
+type IssueResponse = { number: number; title?: string; body?: string; state?: string; labels?: Array<{ name?: string } | string> };
+type ReqOpts = { allowNotFound?: boolean; allowValidationError?: boolean; omitAuth?: boolean };
+
+export class GitHubIssueClient {
+  constructor(private readonly config: ClawMemPluginConfig, private readonly log: { warn?: (msg: string) => void }) {}
+
+  async createIssue(params: { title: string; body: string; labels: string[] }): Promise<IssueResponse> {
+    return this.req<IssueResponse>(this.repoPath("issues"), { method: "POST", body: JSON.stringify(params) });
+  }
+  async updateIssue(n: number, params: { title?: string; body?: string; state?: "open" | "closed"; labels?: string[] }): Promise<IssueResponse> {
+    return this.req<IssueResponse>(this.repoPath(`issues/${n}`), { method: "PATCH", body: JSON.stringify(params) });
+  }
+  async getIssue(n: number): Promise<IssueResponse> {
+    return this.req<IssueResponse>(this.repoPath(`issues/${n}`), { method: "GET" });
+  }
+  async createComment(issueNumber: number, body: string): Promise<void> {
+    await this.req(this.repoPath(`issues/${issueNumber}/comments`), { method: "POST", body: JSON.stringify({ body }) });
+  }
+  async listIssues(params: { labels?: string[]; state?: "open" | "closed" | "all"; page?: number; perPage?: number }): Promise<IssueResponse[]> {
+    const q = new URLSearchParams();
+    q.set("state", params.state ?? "open"); q.set("page", String(params.page ?? 1)); q.set("per_page", String(params.perPage ?? 100));
+    if (params.labels?.length) q.set("labels", params.labels.join(","));
+    return this.req<IssueResponse[]>(`${this.repoPath("issues")}?${q}`, { method: "GET" });
+  }
+  async ensureLabels(labels: string[]): Promise<void> {
+    for (const label of labels) {
+      if (!label.trim()) continue;
+      await this.req(this.repoPath("labels"), { method: "POST",
+        body: JSON.stringify({ name: label, color: resolveLabelColor(label), description: labelDescription(label) }) }, { allowValidationError: true });
+    }
+  }
+  async syncManagedLabels(issueNumber: number, desired: string[]): Promise<void> {
+    const issue = await this.getIssue(issueNumber);
+    const unmanaged = extractLabelNames(issue.labels).filter((l) => !isManagedLabel(l));
+    await this.updateIssue(issueNumber, { labels: [...new Set([...unmanaged, ...desired])] });
+  }
+  async createAnonymousSession(): Promise<AnonymousSessionResponse> {
+    return this.req<AnonymousSessionResponse>("anonymous/session", { method: "POST" }, { omitAuth: true });
+  }
+
+  private repoPath(suffix: string): string {
+    if (!this.config.repo) throw new Error("clawmem repository is not configured");
+    return `repos/${this.config.repo}/${suffix}`;
+  }
+  private async req<T = void>(pathname: string, init: RequestInit, opts: ReqOpts = {}): Promise<T> {
+    if (!this.config.baseUrl) throw new Error("clawmem baseUrl is not configured");
+    if (!opts.omitAuth && !this.config.token) throw new Error("clawmem token is not configured");
+    const base = this.config.baseUrl.replace(/\/+$/, "");
+    const headers: Record<string, string> = { Accept: "application/vnd.github+json", "Content-Type": "application/json" };
+    if (!opts.omitAuth) headers.Authorization = this.config.authScheme === "bearer" ? `Bearer ${this.config.token}` : `token ${this.config.token}`;
+    const res = await fetch(new URL(pathname, `${base}/`), { ...init, headers: { ...headers, ...(init.headers ?? {}) } });
+    if (res.status === 404 && opts.allowNotFound) return undefined as T;
+    if (res.status === 422 && opts.allowValidationError) return undefined as T;
+    if (!res.ok) { const d = await res.text(); throw new Error(`HTTP ${res.status}: ${d || res.statusText}`); }
+    if (res.status === 204) return undefined as T;
+    const text = await res.text();
+    if (!text.trim()) return undefined as T;
+    try { return JSON.parse(text) as T; } catch (e) { this.log.warn?.(`clawmem: failed to parse API response: ${String(e)}`); return undefined as T; }
+  }
+}

package/src/keyed-async-queue.ts

@@ -0,0 +1,26 @@
+/**
+ * A keyed async queue that serializes async tasks per key.
+ * Inlined from openclaw/plugin-sdk/keyed-async-queue to avoid
+ * dependency on platform internals that may not exist in older versions.
+ *
+ * Matches the behaviour of the upstream implementation: a failed task
+ * does not block subsequent tasks on the same key.
+ */
+export class KeyedAsyncQueue {
+  private readonly tails = new Map<string, Promise<void>>();
+
+  enqueue<T>(key: string, task: () => Promise<T>): Promise<T> {
+    const current = (this.tails.get(key) ?? Promise.resolve())
+      .catch(() => void 0)
+      .then(task);
+    const tail = current.then(
+      () => void 0,
+      () => void 0,
+    );
+    this.tails.set(key, tail);
+    tail.finally(() => {
+      if (this.tails.get(key) === tail) this.tails.delete(key);
+    });
+    return current;
+  }
+}

package/src/memory.ts

@@ -0,0 +1,157 @@
+// Memory CRUD, sha256 dedup, and AI-driven memory extraction.
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { LABEL_MEMORY_ACTIVE, LABEL_MEMORY_STALE, MEMORY_TITLE_PREFIX, extractLabelNames, labelVal } from "./config.js";
+import type { GitHubIssueClient } from "./github-client.js";
+import { normalizeMessages } from "./transcript.js";
+import type { ClawMemPluginConfig, NormalizedMessage, ParsedMemoryIssue, SessionMirrorState, TranscriptSnapshot } from "./types.js";
+import { fmtTranscript, localDate, sha256, subKey } from "./utils.js";
+import { parseFlatYaml, stringifyFlatYaml } from "./yaml.js";
+
+type MemoryDecision = { save: string[]; stale: string[] };
+
+export class MemoryStore {
+  constructor(private readonly client: GitHubIssueClient, private readonly api: OpenClawPluginApi, private readonly config: ClawMemPluginConfig) {}
+
+  async search(query: string, limit: number): Promise<ParsedMemoryIssue[]> {
+    const memories = await this.list("active");
+    const q = query.trim().toLowerCase();
+    const tokens = q.split(/[^a-z0-9]+/i).filter((t) => t.length > 1);
+    return memories
+      .map((m) => {
+        const hay = `${m.title}\n${m.detail}`.toLowerCase();
+        let score = hay.includes(q) ? 10 : 0;
+        for (const t of tokens) if (hay.includes(t)) score += 1;
+        return { m, score };
+      })
+      .filter((e) => e.score > 0)
+      .sort((a, b) => b.score - a.score || b.m.issueNumber - a.m.issueNumber)
+      .slice(0, limit)
+      .map((e) => e.m);
+  }
+
+  async syncFromConversation(session: SessionMirrorState, snapshot: TranscriptSnapshot): Promise<void> {
+    try {
+      const decision = await this.generateDecision(session, snapshot);
+      const { savedCount, staledCount } = await this.applyDecision(session.sessionId, decision);
+      if (savedCount > 0 || staledCount > 0)
+        this.api.logger.info?.(`clawmem: synced memories for ${session.sessionId} (saved=${savedCount}, stale=${staledCount})`);
+    } catch (error) {
+      this.api.logger.warn(`clawmem: memory capture failed: ${String(error)}`);
+    }
+  }
+
+  private async list(status: "active" | "stale" | "all"): Promise<ParsedMemoryIssue[]> {
+    const labels = ["type:memory"];
+    if (status === "active") labels.push(LABEL_MEMORY_ACTIVE);
+    else if (status === "stale") labels.push(LABEL_MEMORY_STALE);
+    const out: ParsedMemoryIssue[] = [];
+    for (let page = 1; page <= 20; page++) {
+      const batch = await this.client.listIssues({ labels, state: "all", page, perPage: 100 });
+      for (const issue of batch) { const p = this.parseIssue(issue); if (p) out.push(p); }
+      if (batch.length < 100) break;
+    }
+    return out;
+  }
+
+  private parseIssue(issue: { number: number; title?: string; body?: string; labels?: Array<{ name?: string } | string> }): ParsedMemoryIssue | null {
+    const labels = extractLabelNames(issue.labels);
+    if (!labels.includes("type:memory")) return null;
+    const sessionId = labelVal(labels, "session:"), date = labelVal(labels, "date:");
+    const topics = labels.filter((l) => l.startsWith("topic:")).map((l) => l.slice(6).trim()).filter(Boolean);
+    const rawBody = (issue.body ?? "").trim();
+    const body = rawBody ? parseFlatYaml(rawBody) : {};
+    const detail = body.detail?.trim() || rawBody;
+    if (!sessionId || !date || !detail) return null;
+    return {
+      issueNumber: issue.number, title: issue.title?.trim() || "",
+      memoryId: body.memory_id?.trim() || String(issue.number),
+      memoryHash: body.memory_hash?.trim() || undefined,
+      sessionId, date, detail,
+      ...(topics.length > 0 ? { topics } : {}),
+      status: labels.includes(LABEL_MEMORY_STALE) ? "stale" : "active",
+    };
+  }
+
+  private async applyDecision(sessionId: string, decision: MemoryDecision): Promise<{ savedCount: number; staledCount: number }> {
+    const allActive = await this.list("active");
+    const activeById = new Map(allActive.map((m) => [m.memoryId, m]));
+    const existingHashes = new Set(allActive.map((m) => m.memoryHash || sha256(norm(m.detail))));
+    let savedCount = 0;
+    for (const raw of decision.save) {
+      const detail = norm(raw);
+      if (!detail) continue;
+      const hash = sha256(detail);
+      if (existingHashes.has(hash)) continue;
+      const date = localDate(), labels = memLabels(sessionId, date, "active");
+      const title = `${MEMORY_TITLE_PREFIX}${trunc(detail, 72)}`;
+      const body = stringifyFlatYaml([["memory_hash", hash], ["detail", detail]]);
+      await this.client.ensureLabels(labels);
+      await this.client.createIssue({ title, body, labels });
+      existingHashes.add(hash);
+      savedCount++;
+    }
+    let staledCount = 0;
+    for (const id of [...new Set(decision.stale.map((s) => s.trim()).filter(Boolean))]) {
+      const mem = activeById.get(id);
+      if (!mem) continue;
+      await this.client.ensureLabels([LABEL_MEMORY_STALE]);
+      await this.client.syncManagedLabels(mem.issueNumber, memLabels(mem.sessionId, mem.date, "stale"));
+      staledCount++;
+    }
+    return { savedCount, staledCount };
+  }
+
+  private async generateDecision(session: SessionMirrorState, snapshot: TranscriptSnapshot): Promise<MemoryDecision> {
+    if (snapshot.messages.length === 0) return { save: [], stale: [] };
+    const recent = (await this.list("active")).sort((a, b) => b.issueNumber - a.issueNumber).slice(0, 20);
+    const existingBlock = recent.length === 0 ? "None." : recent.map((m) => `[${m.memoryId}] ${m.detail}`).join("\n");
+    const subagent = this.api.runtime.subagent;
+    const sessionKey = subKey(session, "memory");
+    const message = [
+      "Extract durable memories from the conversation below.",
+      'Return JSON only in the form {"save":["..."],"stale":["memory-id"]}.',
+      "Use save for stable, reusable facts, preferences, decisions, constraints, and ongoing context worth remembering later.",
+      "Use stale for existing memory IDs only when the conversation clearly supersedes or invalidates them.",
+      "Do not save temporary requests, startup boilerplate, tool chatter, summaries about internal helper sessions, or one-off operational details.",
+      "Prefer empty arrays when nothing durable should be remembered.",
+      "", "<existing-active-memories>", existingBlock, "</existing-active-memories>",
+      "", "<conversation>", fmtTranscript(snapshot.messages), "</conversation>",
+    ].join("\n");
+    try {
+      const run = await subagent.run({
+        sessionKey, message, deliver: false, lane: "clawmem-memory",
+        idempotencyKey: sha256(`${session.sessionId}:${snapshot.messages.length}:memory-decision`),
+        extraSystemPrompt: "You extract durable memory updates from OpenClaw conversations. Output JSON only with string arrays save and stale.",
+      });
+      const wait = await subagent.waitForRun({ runId: run.runId, timeoutMs: this.config.summaryWaitTimeoutMs });
+      if (wait.status === "timeout") throw new Error("memory decision subagent timed out");
+      if (wait.status === "error") throw new Error(wait.error || "memory decision subagent failed");
+      const msgs = normalizeMessages((await subagent.getSessionMessages({ sessionKey, limit: 50 })).messages);
+      const text = [...msgs].reverse().find((e) => e.role === "assistant" && e.text.trim())?.text;
+      if (!text) throw new Error("memory decision subagent returned no assistant text");
+      return parseDecision(text);
+    } finally { subagent.deleteSession({ sessionKey, deleteTranscript: true }).catch(() => {}); }
+  }
+}
+
+function memLabels(sessionId: string, date: string, status: "active" | "stale"): string[] {
+  return ["type:memory", `session:${sessionId}`, `date:${date}`, status === "active" ? LABEL_MEMORY_ACTIVE : LABEL_MEMORY_STALE];
+}
+function norm(v: string): string { return v.replace(/\s+/g, " ").trim(); }
+function trunc(v: string, max: number): string { const s = norm(v); return s.length <= max ? s : `${s.slice(0, max - 1).trimEnd()}…`; }
+function parseDecision(raw: string): MemoryDecision {
+  const tryParse = (s: string): MemoryDecision | null => {
+    try {
+      const p = JSON.parse(s) as Record<string, unknown>;
+      return { save: Array.isArray(p.save) ? p.save.filter((v): v is string => typeof v === "string") : [],
+               stale: Array.isArray(p.stale) ? p.stale.filter((v): v is string => typeof v === "string") : [] };
+    } catch { return null; }
+  };
+  const t = raw.trim();
+  return tryParse(t) ?? (() => {
+    const f = /^```(?:json)?\s*([\s\S]*?)```$/i.exec(t);
+    const nested = f?.[1] ? tryParse(f[1].trim()) : null;
+    if (nested) return nested;
+    throw new Error("memory decision subagent returned invalid JSON");
+  })();
+}

package/src/service.ts

@@ -0,0 +1,199 @@
+// Thin orchestrator: wires conversation mirroring, memory store, and plugin lifecycle.
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { isPluginConfigured, 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";
+
+type TurnPayload = { sessionId?: string; sessionKey?: string; agentId?: string; messages: unknown[] };
+type FinalizePayload = { sessionId?: string; sessionKey?: string; sessionFile?: string; agentId?: string; reason?: string; messages?: unknown[] };
+
+class ClawMemService {
+  private readonly config: ClawMemPluginConfig;
+  private readonly client: GitHubIssueClient;
+  private readonly conv: ConversationMirror;
+  private readonly mem: MemoryStore;
+  private readonly queue = new KeyedAsyncQueue();
+  private readonly stateQueue = new KeyedAsyncQueue();
+  private readonly pending = new Set<Promise<unknown>>();
+  private readonly syncTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  private statePath = "";
+  private state: PluginState = { version: 1, sessions: {} };
+  private unsubTranscript?: () => void;
+  private loadPromise: Promise<void> | null = null;
+  private configPromise: Promise<boolean> | null = null;
+
+  constructor(private readonly api: OpenClawPluginApi) {
+    this.config = resolvePluginConfig(api);
+    this.client = new GitHubIssueClient(this.config, api.logger);
+    this.conv = new ConversationMirror(this.client, api, this.config);
+    this.mem = new MemoryStore(this.client, api, this.config);
+  }
+
+  register(): void {
+    this.api.on("before_agent_start", async (ev) => this.handleRecall(ev.prompt));
+    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.api.registerService({
+      id: "clawmem",
+      start: async (ctx) => {
+        this.statePath = resolveStatePath(ctx.stateDir);
+        await this.ensureLoaded();
+        const ok = await this.ensureConfigured();
+        this.unsubTranscript = this.api.runtime.events.onSessionTranscriptUpdate((u) => {
+          void this.track(this.handleTranscript(u.sessionFile)).catch((e) => this.warn("transcript update", e));
+        });
+        if (ok) this.api.logger.info?.(`clawmem: mirroring sessions to ${this.config.repo} via ${this.config.baseUrl}`);
+        else this.api.logger.warn(`clawmem: missing repo/token and automatic provisioning failed via ${this.config.baseUrl}; sync will retry on the next use`);
+      },
+      stop: async () => {
+        this.unsubTranscript?.();
+        for (const t of this.syncTimers.values()) clearTimeout(t);
+        this.syncTimers.clear();
+        await Promise.allSettled([...this.pending]);
+      },
+    });
+  }
+
+  private async handleRecall(prompt: unknown): Promise<{ prependContext: string } | void> {
+    if (typeof prompt !== "string" || prompt.trim().length < 5) return;
+    if (!(await this.ensureConfigured())) return;
+    try {
+      const memories = await this.mem.search(prompt, this.config.memoryRecallLimit);
+      if (memories.length === 0) return;
+      const text = memories.map((m) => `- ${m.detail}`).join("\n");
+      return { prependContext: `<relevant-memories>\nThe following active memories may be relevant to this conversation:\n${text}\n</relevant-memories>` };
+    } catch (error) { this.api.logger.warn(`clawmem: memory recall failed: ${String(error)}`); }
+  }
+
+  private async handleTranscript(sessionFile: string): Promise<void> {
+    let snap: TranscriptSnapshot;
+    try { snap = await readTranscriptSnapshot(sessionFile); } catch (e) { this.warn("transcript read", e); return; }
+    if (!snap.sessionId || !this.conv.shouldMirror(snap.sessionId, snap.messages)) return;
+    if (!(await this.ensureConfigured())) return;
+    await this.enqueueSession(snap.sessionId, async () => {
+      const s = this.getOrCreate(snap.sessionId!);
+      s.sessionFile = sessionFile;
+      s.updatedAt = new Date().toISOString();
+      await this.conv.ensureIssue(s, snap);
+      await this.persistState();
+    });
+  }
+
+  private scheduleTurn(p: TurnPayload): void {
+    if (!p.sessionId) return;
+    const prev = this.syncTimers.get(p.sessionId);
+    if (prev) clearTimeout(prev);
+    const timer = setTimeout(() => {
+      this.syncTimers.delete(p.sessionId!);
+      void this.track(this.enqueueSession(p.sessionId!, () => this.syncTurn(p))).catch((e) => this.warn("turn sync", e));
+    }, this.config.turnCommentDelayMs);
+    timer.unref?.();
+    this.syncTimers.set(p.sessionId, timer);
+  }
+
+  private async syncTurn(p: TurnPayload): Promise<void> {
+    if (!p.sessionId || !(await this.ensureConfigured())) return;
+    const s = this.getOrCreate(p.sessionId);
+    s.sessionKey = p.sessionKey ?? s.sessionKey; s.agentId = p.agentId ?? s.agentId; s.updatedAt = new Date().toISOString();
+    const snap = await this.conv.loadSnapshot(s, p.messages);
+    if (!this.conv.shouldMirror(s.sessionId, snap.messages) || snap.messages.length === 0) { await this.persistState(); return; }
+    await this.conv.ensureIssue(s, snap);
+    await this.conv.syncLabels(s, snap, false);
+    const next = snap.messages.slice(s.lastMirroredCount);
+    if (next.length > 0) { const n = await this.conv.appendComments(s.issueNumber!, next); s.lastMirroredCount += n; s.turnCount += n; }
+    await this.persistState();
+  }
+
+  private enqueueFinalize(p: FinalizePayload): void {
+    if (!p.sessionId) return;
+    const prev = this.syncTimers.get(p.sessionId);
+    if (prev) { clearTimeout(prev); this.syncTimers.delete(p.sessionId); }
+    void this.track(this.enqueueSession(p.sessionId, () => this.finalize(p))).catch((e) => this.warn("finalize", e));
+  }
+
+  private async finalize(p: FinalizePayload): Promise<void> {
+    if (!p.sessionId || !(await this.ensureConfigured())) return;
+    const s = this.getOrCreate(p.sessionId);
+    if (s.finalizedAt) return;
+    s.sessionKey = p.sessionKey ?? s.sessionKey; s.sessionFile = p.sessionFile ?? s.sessionFile;
+    s.agentId = p.agentId ?? s.agentId; s.updatedAt = new Date().toISOString();
+    const snap = await this.conv.loadSnapshot(s, p.messages ?? []);
+    if (!this.conv.shouldMirror(s.sessionId, snap.messages)) { await this.persistState(); return; }
+    if (snap.messages.length === 0 && !s.issueNumber) { await this.persistState(); return; }
+    await this.conv.ensureIssue(s, snap);
+    const next = snap.messages.slice(s.lastMirroredCount);
+    let allOk = true;
+    if (next.length > 0) { const n = await this.conv.appendComments(s.issueNumber!, next); s.lastMirroredCount += n; s.turnCount += n; allOk = n === next.length; }
+    let summary = "pending";
+    try { summary = await this.conv.generateSummary(s, snap); } catch (e) { summary = `failed: ${String(e)}`; }
+    await this.conv.syncLabels(s, snap, true);
+    await this.conv.syncBody(s, snap, summary, true);
+    await this.mem.syncFromConversation(s, snap);
+    if (allOk) s.finalizedAt = new Date().toISOString();
+    await this.persistState();
+  }
+
+  // --- Infrastructure ---
+
+  private enqueueSession<T>(sessionId: string, task: () => Promise<T>): Promise<T> {
+    return this.queue.enqueue(sessionId, async () => { await this.ensureLoaded(); return task(); });
+  }
+  private track<T>(promise: Promise<T>): Promise<T> {
+    this.pending.add(promise); void promise.finally(() => this.pending.delete(promise)); return promise;
+  }
+  private getOrCreate(sessionId: string): SessionMirrorState {
+    if (this.state.sessions[sessionId]) return this.state.sessions[sessionId];
+    const now = new Date().toISOString();
+    const s: SessionMirrorState = { sessionId, lastMirroredCount: 0, turnCount: 0, createdAt: now, updatedAt: now };
+    this.state.sessions[sessionId] = s;
+    return s;
+  }
+  private async persistState(): Promise<void> {
+    if (!this.statePath) this.statePath = resolveStatePath(this.api.runtime.state.resolveStateDir());
+    await this.stateQueue.enqueue("state", () => saveState(this.statePath, this.state));
+  }
+  private async ensureLoaded(): Promise<void> {
+    if (this.loadPromise) return this.loadPromise;
+    this.loadPromise = (async () => {
+      if (!this.statePath) this.statePath = resolveStatePath(this.api.runtime.state.resolveStateDir());
+      this.state = await loadState(this.statePath);
+    })();
+    return this.loadPromise;
+  }
+  private async ensureConfigured(): Promise<boolean> {
+    if (isPluginConfigured(this.config)) return true;
+    if (this.configPromise) return this.configPromise;
+    const p = this.bootstrap();
+    this.configPromise = p;
+    try { return await p; } finally { if (this.configPromise === p) this.configPromise = null; }
+  }
+  private async bootstrap(): Promise<boolean> {
+    if (!this.config.baseUrl) { this.api.logger.warn("clawmem: cannot provision Git credentials without a baseUrl"); return false; }
+    try {
+      const sess = await this.client.createAnonymousSession();
+      await this.persistPluginConfig({ baseUrl: this.config.baseUrl, authScheme: "token", token: sess.token, repo: sess.repo_full_name });
+      this.config.authScheme = "token"; this.config.token = sess.token; this.config.repo = sess.repo_full_name;
+      this.api.logger.info?.(`clawmem: provisioned Git credentials for ${sess.repo_full_name} via ${this.config.baseUrl}`);
+      return true;
+    } catch (error) { this.api.logger.warn(`clawmem: failed to provision Git credentials via ${this.config.baseUrl}: ${String(error)}`); return false; }
+  }
+  private async persistPluginConfig(values: Partial<ClawMemPluginConfig>): 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>) : {};
+    const ex = asRecord(entries[this.api.id]), exCfg = asRecord(ex.config);
+    await this.api.runtime.config.writeConfigFile({ ...root, plugins: { ...(plugins ?? {}), entries: { ...entries, [this.api.id]: { ...ex, config: { ...exCfg, ...values } } } } });
+  }
+  private warn(scope: string, error: unknown): void { this.api.logger.warn(`clawmem: ${scope} failed: ${String(error)}`); }
+}
+
+function asRecord(v: unknown): Record<string, unknown> { return v && typeof v === "object" ? (v as Record<string, unknown>) : {}; }
+
+export function createClawMemPlugin(api: OpenClawPluginApi): void { new ClawMemService(api).register(); }