@clawmem-ai/clawmem 0.1.7 → 0.1.9

package/README.md

@@ -4,8 +4,9 @@
 
 **What it does:**
 - Creates one `type:conversation` issue per session, mirrors the full transcript as comments.
-- On session end: auto-extracts durable memories and stores each as a `type:memory` issue.
+- During request-scoped hooks: best-effort extracts durable memories and stores each as a `type:memory` issue.
 - On session start: searches active memories by relevance and injects them into context.
+- Lets agents inspect memory indexes and schema, fetch exact memories, update canonical facts in place, and write structured memories with `kind:*` and `topic:*` labels through plugin tools.
 
 ---
 
@@ -33,10 +34,13 @@ Finally: your `IDENTITY.md` is not something you fill out on day one. It fills i
 
 ```bash
 openclaw plugins install @clawmem-ai/clawmem
+openclaw plugins enable clawmem
+openclaw config set plugins.slots.memory clawmem
+openclaw config validate
 openclaw gateway restart
 ```
 
-After restart, clawmem provisions per-agent memory repos on `git.clawmem.ai` as each agent is first used, then writes that agent's `token` + `repo` back into your config under `plugins.entries.clawmem.config.agents.<agentId>`. Memories start accumulating from that agent's next session.
+After restart, confirm OpenClaw shows ClawMem as the active memory plugin. clawmem then provisions per-agent memory repos on `git.clawmem.ai` as each agent is first used, then writes that agent's `token` + `repo` back into your config under `plugins.entries.clawmem.config.agents.<agentId>`. Memories start accumulating from that agent's next session.
 
 ---
 
@@ -75,7 +79,7 @@ Without it, every session starts from zero. With it, what you learn persists. On
 After installing clawmem, you have two memory systems running in parallel:
 
 1. **Workspace files** (`MEMORY.md`, `SOUL.md`, etc.) — always injected into every session via system prompt
-2. **clawmem** — auto-extracts memories at session end; selectively injects by relevance at session start
+2. **clawmem** — auto-extracts memories during request-scoped maintenance; selectively injects by relevance at session start
 
 These two systems do not sync. Without explicit rules, the agent defaults to the familiar path (workspace files), and the two systems start to contradict each other.
 
@@ -113,7 +117,7 @@ clawmem is my brain. One system per job — no exceptions:
 | What | Where |
 |---|---|
 | Credentials / API keys | `knowledge/MEMORY.md` (always injected) |
-| Everything I learn, conclude, or figure out | clawmem only — auto-captured at session end |
+| Everything I learn, conclude, or figure out | clawmem only — auto-captured during request-scoped maintenance |
 | Files | Only when a tool or another human needs to read them |
 | Workspace versioning | clawmem git service (not github.com) |
 
@@ -144,7 +148,7 @@ Strip everything except credentials. Add a header comment:
 
 ## Locking Key Insights Manually
 
-clawmem auto-extracts memories at session end — but important insights deserve to be locked immediately, not left to chance extraction.
+clawmem auto-extracts memories during later request-scoped maintenance — but important insights deserve to be locked immediately, not left to chance extraction.
 
 After any significant realization, create a memory issue directly:
 
@@ -158,7 +162,7 @@ curl -X POST "https://git.clawmem.ai/api/v3/repos/$CLAWMEM_REPO/issues" \
   -d '{
     "title": "Memory: <concise title>",
     "body": "<the insight, in plain language>",
-    "labels": ["type:memory", "memory-status:active"]
+    "labels": ["type:memory"]
   }'
 ```
 
@@ -189,7 +193,7 @@ GH_HOST=git.clawmem.ai GH_TOKEN=$CLAWMEM_TOKEN \
   gh issue create --repo <owner/team-memory> \
     --title "Memory: ..." \
     --body "..." \
-    --label "type:memory,memory-status:active,source:team"
+    --label "type:memory,source:team"
 ```
 
 **Read team memories:**
@@ -197,7 +201,8 @@ GH_HOST=git.clawmem.ai GH_TOKEN=$CLAWMEM_TOKEN \
 ```bash
 GH_HOST=git.clawmem.ai GH_TOKEN=$CLAWMEM_TOKEN \
   gh issue list --repo <owner/team-memory> \
-    --label "memory-status:active" \
+    --state open \
+    --label "type:memory" \
     --json number,title,body
 ```
 
@@ -282,10 +287,6 @@ Full config with all options:
           memoryTitlePrefix: "Memory: ",
           defaultLabels: ["source:openclaw"],
           agentLabelPrefix: "agent:",
-          activeStatusLabel: "status:active",
-          closedStatusLabel: "status:closed",
-          memoryActiveStatusLabel: "memory-status:active",
-          memoryStaleStatusLabel: "memory-status:stale",
           autoCreateLabels: true,
           closeIssueOnReset: true,
           turnCommentDelayMs: 1000,
@@ -304,6 +305,11 @@ Full config with all options:
 
 - Conversation comments exclude tool calls, tool results, system messages, and heartbeat noise.
 - Summary failures do not block finalization; the `summary` field is written as `failed: ...`.
-- Memory search and auto-injection only return `memory-status:active` issues.
-- Durable memories are auto-captured on session finalize — no memory tools are injected into the agent tool list.
-- Memory issue bodies store only the detail text; metadata comes from labels and issue number.
+- Memory search and auto-injection only return open `type:memory` issues. Closed memory issues are treated as stale.
+- `memory_recall` now prefers the backend `/api/v3/search/issues` endpoint scoped to the current repo plus `label:"type:memory"`; if backend search fails, clawmem falls back to local lexical ranking.
+- Durable memories are extracted best-effort during later request-scoped maintenance, not by background subagent work after a request has already ended.
+- The plugin exposes `memory_list`, `memory_get`, `memory_labels`, `memory_recall`, `memory_store`, `memory_update`, and `memory_forget` for mid-session use.
+- `memory_store` accepts optional schema hints such as kind and topics; the plugin normalizes them into managed `kind:*` and `topic:*` labels.
+- `memory_update` updates one existing memory issue in place; use it for evolving canonical facts or active tasks instead of creating a duplicate node.
+- Conversation lifecycle is stored in native issue state (`open` while live, `closed` after finalize); memory lifecycle uses native issue state too (`open` active, `closed` stale).
+- Memory issue bodies store the durable detail plus flat metadata such as `memory_hash` and logical `date`; labels are reserved for schema and routing.

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "clawmem",
   "name": "ClawMem",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Mirror OpenClaw sessions into GitHub-compatible issues and comments.",
   "kind": "memory",
   "configSchema": {
@@ -148,16 +148,20 @@
       "help": "Dynamic agent label prefix, for example agent:coder."
     },
     "activeStatusLabel": {
-      "label": "Active Status Label"
+      "label": "Active Status Label",
+      "help": "Deprecated compatibility setting. Conversation lifecycle now uses native issue state."
     },
     "closedStatusLabel": {
-      "label": "Closed Status Label"
+      "label": "Closed Status Label",
+      "help": "Deprecated compatibility setting. Conversation lifecycle now uses native issue state."
     },
     "memoryActiveStatusLabel": {
-      "label": "Memory Active Status Label"
+      "label": "Memory Active Status Label",
+      "help": "Deprecated compatibility setting. Memory lifecycle now uses native issue state."
     },
     "memoryStaleStatusLabel": {
-      "label": "Memory Stale Status Label"
+      "label": "Memory Stale Status Label",
+      "help": "Deprecated compatibility setting. Memory lifecycle now uses native issue state."
     },
     "autoCreateLabels": {
       "label": "Auto Create Labels"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawmem-ai/clawmem",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Mirror OpenClaw sessions into GitHub-compatible issues and comments.",
   "type": "module",
   "license": "MIT",

package/src/config.ts

@@ -12,7 +12,7 @@ export const LABEL_CLOSED = "status:closed";
 export const LABEL_MEMORY_ACTIVE = "memory-status:active";
 export const LABEL_MEMORY_STALE = "memory-status:stale";
 
-const MANAGED_PREFIXES = ["type:", "session:", "date:", "topic:", "agent:", "source:"];
+const MANAGED_PREFIXES = ["type:", "kind:", "session:", "date:", "topic:", "agent:", "source:"];
 const MANAGED_EXACT = new Set([LABEL_ACTIVE, LABEL_CLOSED, LABEL_MEMORY_ACTIVE, LABEL_MEMORY_STALE]);
 
 export function resolvePluginConfig(api: OpenClawPluginApi): ClawMemPluginConfig {
@@ -67,6 +67,7 @@ export function resolveLabelColor(label: string): string {
   if (label.startsWith("status:")) return "b60205";
   if (label.startsWith("memory-status:")) return label.endsWith(":stale") ? "d93f0b" : "0e8a16";
   if (label.startsWith("type:")) return label === "type:memory" ? "5319e7" : "1d76db";
+  if (label.startsWith("kind:")) return "5319e7";
   if (label.startsWith("date:")) return "c5def5";
   if (label.startsWith("topic:")) return "fbca04";
   if (label.startsWith("session:")) return "bfdadc";
@@ -76,7 +77,7 @@ export function resolveLabelColor(label: string): string {
 }
 
 export function labelDescription(label: string): string {
-  for (const [pfx, d] of [["type:", "Issue type"], ["memory-status:", "Memory lifecycle status"],
+  for (const [pfx, d] of [["type:", "Issue type"], ["kind:", "Memory kind"], ["memory-status:", "Memory lifecycle status"],
     ["status:", "Conversation lifecycle status"], ["session:", "Session association"],
     ["date:", "Date"], ["topic:", "Topic"], ["agent:", "Agent"], ["source:", "Source"]] as const)
     if (label.startsWith(pfx)) return `${d} label managed by clawmem.`;

package/src/conversation.test.ts

@@ -0,0 +1,70 @@
+// Tests for conversation title derivation logic.
+import { deriveInitialTitle } from "./conversation.js";
+import type { NormalizedMessage } from "./types.js";
+
+function msg(role: string, text: string): NormalizedMessage {
+  return { role, text };
+}
+
+const tests: Array<{ name: string; messages: NormalizedMessage[]; sessionId: string; expected: string }> = [
+  {
+    name: "returns placeholder regardless of user message content",
+    messages: [msg("user", "How do I configure Redis rate limiting?")],
+    sessionId: "abc123",
+    expected: "Session: abc123",
+  },
+  {
+    name: "returns placeholder for long messages",
+    messages: [msg("user", "I need help with configuring the distributed rate limiting system for our production Redis cluster")],
+    sessionId: "abc123",
+    expected: "Session: abc123",
+  },
+  {
+    name: "returns placeholder for messages with markdown",
+    messages: [msg("user", "## How do I **configure** `Redis` rate limiting?")],
+    sessionId: "abc123",
+    expected: "Session: abc123",
+  },
+  {
+    name: "returns placeholder for short messages",
+    messages: [msg("user", "hi")],
+    sessionId: "abc-def-123",
+    expected: "Session: abc-def-123",
+  },
+  {
+    name: "returns placeholder when no user messages",
+    messages: [msg("assistant", "Hello!")],
+    sessionId: "xyz-789",
+    expected: "Session: xyz-789",
+  },
+  {
+    name: "returns placeholder for empty messages",
+    messages: [],
+    sessionId: "empty-sess",
+    expected: "Session: empty-sess",
+  },
+  {
+    name: "returns placeholder with session ID for any input",
+    messages: [msg("assistant", "Welcome!"), msg("user", "Fix the login bug please")],
+    sessionId: "abc",
+    expected: "Session: abc",
+  },
+];
+
+let passed = 0;
+let failed = 0;
+
+for (const t of tests) {
+  const got = deriveInitialTitle(t.messages, t.sessionId);
+  const ok = got === t.expected;
+  if (!ok) {
+    console.error(`FAIL: ${t.name}\n  got:      ${JSON.stringify(got)}\n  expected: ${JSON.stringify(t.expected)}`);
+    failed++;
+  } else {
+    console.log(`PASS: ${t.name}`);
+    passed++;
+  }
+}
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/src/conversation.ts

@@ -2,12 +2,12 @@
 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, extractLabelNames } from "./config.js";
+import { AGENT_LABEL_PREFIX, DEFAULT_LABELS, SESSION_TITLE_PREFIX, extractLabelNames } 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";
+import { parseFlatYaml, stringifyFlatYaml } from "./yaml.js";
 
 export class ConversationMirror {
   constructor(private readonly client: GitHubIssueClient, private readonly api: OpenClawPluginApi, private readonly config: ClawMemPluginConfig) {}
@@ -47,26 +47,30 @@ export class ConversationMirror {
       );
       this.resetIssueBinding(session);
     }
-    const title = `${SESSION_TITLE_PREFIX}${session.sessionId}`;
+    // Use placeholder title; real title is generated by LLM once enough messages are available.
+    const title = deriveInitialTitle(snapshot.messages, 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.titleSource = "placeholder";
     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> {
+  async syncBody(session: SessionMirrorState, snapshot: TranscriptSnapshot, summary: string, closed: boolean, titleOverride?: string): Promise<void> {
     if (!session.issueNumber) return;
-    const title = `${SESSION_TITLE_PREFIX}${session.sessionId}`;
+    // Prefer explicit override (LLM-generated title), then keep existing title, then fall back to session ID.
+    const title = titleOverride?.trim() || session.issueTitle || `${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;
+    if (titleOverride?.trim()) session.titleSource = "llm";
     session.lastSummaryHash = hash;
   }
 
@@ -86,22 +90,28 @@ export class ConversationMirror {
     return count;
   }
 
-  async generateSummary(session: SessionMirrorState, snapshot: TranscriptSnapshot): Promise<string> {
+  async generateSummaryAndTitle(session: SessionMirrorState, snapshot: TranscriptSnapshot): Promise<{ summary: string; title?: 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":"..."}',
+      "Summarize the following conversation and generate a short title.",
+      'Return valid JSON only in the form {"summary":"...","title":"..."}',
       "The summary should be concise, factual, and written in 2-4 sentences.",
       "Do not include markdown, bullet points, or analysis.",
+      "",
+      "Title rules:",
+      "- Under 50 characters, accurately describe the main topic or task.",
+      "- Should let someone immediately know what the conversation is about.",
+      "- Must be in the same language as the majority of the conversation content.",
+      "- Good: precise, descriptive, specific. Bad: vague, overly creative, generic.",
       "", "<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.",
+        idempotencyKey: sha256(`${session.sessionId}:${snapshot.messages.length}:summary-v2`),
+        extraSystemPrompt: "You summarize conversations and generate accurate, descriptive titles. Output JSON only with string fields summary and title.",
       });
       const wait = await subagent.waitForRun({ runId: run.runId, timeoutMs: this.config.summaryWaitTimeoutMs });
       if (wait.status === "timeout") throw new Error("summary subagent timed out");
@@ -109,24 +119,162 @@ export class ConversationMirror {
       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);
+      return parseSummaryAndTitle(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 the title has not yet been generated by LLM, generate an accurate title from the full conversation and update the issue. */
+  async syncTitle(session: SessionMirrorState, snapshot: TranscriptSnapshot): Promise<void> {
+    if (!session.issueNumber) return;
+    if (session.titleSource === "llm") return;
+    if (snapshot.messages.length < 2) return;
+    try {
+      const title = await this.generateTitle(session, snapshot);
+      if (title) {
+        await this.client.updateIssue(session.issueNumber, { title });
+        session.issueTitle = title;
+        session.titleSource = "llm";
+      }
+    } catch (e) {
+      this.api.logger.warn(`clawmem: title sync failed: ${String(e)}`);
+    }
+  }
+
+  /** Generate an accurate, descriptive title from the full conversation content via LLM. */
+  async generateTitle(session: SessionMirrorState, snapshot: TranscriptSnapshot): Promise<string | undefined> {
+    if (snapshot.messages.length === 0) return undefined;
+    const subagent = this.api.runtime.subagent;
+    const sessionKey = subKey(session, "title");
+    const message = [
+      "Generate a short, accurate title for the following conversation.",
+      'Return valid JSON only in the form {"title":"..."}',
+      "",
+      "Title rules:",
+      "- Under 50 characters.",
+      "- Accurately describe the main topic or task of the conversation.",
+      "- Should let someone immediately know what the conversation is about.",
+      "- Must be in the same language as the majority of the conversation content.",
+      "- Good: precise, descriptive, specific. Bad: vague, overly creative, generic.",
+      "",
+      "<conversation>",
+      fmtTranscript(snapshot.messages),
+      "</conversation>",
+    ].join("\n");
+    try {
+      const run = await subagent.run({
+        sessionKey, message, deliver: false, lane: "clawmem-title",
+        idempotencyKey: sha256(`${session.sessionId}:${snapshot.messages.length}:title-v1`),
+        extraSystemPrompt: "You generate accurate, descriptive titles for conversations. Output JSON only with a string field title.",
+      });
+      const wait = await subagent.waitForRun({ runId: run.runId, timeoutMs: 30000 });
+      if (wait.status === "timeout" || wait.status === "error") return undefined;
+      const msgs = normalizeMessages((await subagent.getSessionMessages({ sessionKey, limit: 10 })).messages);
+      const text = [...msgs].reverse().find((e) => e.role === "assistant" && e.text.trim())?.text;
+      if (!text) return undefined;
+      return parseTitle(text);
+    } catch (e) {
+      this.api.logger.warn(`clawmem: title generation failed: ${String(e)}`);
+      return undefined;
+    } finally {
+      subagent.deleteSession({ sessionKey, deleteTranscript: true }).catch(() => {});
+    }
+  }
+
+  /** Re-title all existing conversation issues. Uses summary when available, falls back to reading comments. */
+  async retitleConversations(): Promise<{ updated: number; skipped: number; failed: number; retitledIssues: number[] }> {
+    let updated = 0, skipped = 0, failed = 0;
+    const retitledIssues: number[] = [];
+    let page = 1;
+    while (true) {
+      const issues = await this.client.listIssues({ labels: ["type:conversation"], state: "all", page, perPage: 50 });
+      if (issues.length === 0) break;
+      for (const issue of issues) {
+        try {
+          const yaml = parseFlatYaml(issue.body || "");
+          const summary = yaml.summary;
+          let titleInput: string | undefined;
+          if (summary && summary !== "pending" && !summary.startsWith("failed:")) {
+            titleInput = summary;
+          } else {
+            // No usable summary — reconstruct conversation from issue comments.
+            const comments = await this.client.listComments(issue.number, { perPage: 50 });
+            const conversationText = comments
+              .map((c) => c.body?.trim())
+              .filter((b): b is string => Boolean(b))
+              .join("\n\n");
+            if (conversationText.length >= 20) {
+              // Cap to avoid excessive token usage in LLM call.
+              titleInput = conversationText.length > 4000 ? conversationText.slice(0, 4000) + "\n..." : conversationText;
+            }
+          }
+          if (!titleInput) { skipped++; continue; }
+          const title = await this.generateTitleFromText(titleInput, `retitle-${issue.number}`);
+          if (!title) { skipped++; continue; }
+          await this.client.updateIssue(issue.number, { title });
+          this.api.logger.info?.(`clawmem: retitled issue #${issue.number} -> "${title}"`);
+          retitledIssues.push(issue.number);
+          updated++;
+        } catch (e) {
+          this.api.logger.warn(`clawmem: retitle failed for issue #${issue.number}: ${String(e)}`);
+          failed++;
+        }
+      }
+      if (issues.length < 50) break;
+      page++;
+    }
+    return { updated, skipped, failed, retitledIssues };
+  }
+
+  private async generateTitleFromText(text: string, uniqueKey: string): Promise<string | undefined> {
+    const subagent = this.api.runtime.subagent;
+    const sessionKey = `clawmem-${uniqueKey}`;
+    const message = [
+      "Generate a short, accurate title based on the following conversation content.",
+      'Return valid JSON only in the form {"title":"..."}',
+      "",
+      "Title rules:",
+      "- Under 50 characters.",
+      "- Accurately describe the main topic or task.",
+      "- Should let someone immediately know what the conversation was about.",
+      "- Must be in the same language as the content.",
+      "- Good: precise, descriptive, specific. Bad: vague, overly creative, generic.",
+      "",
+      "<content>",
+      text,
+      "</content>",
+    ].join("\n");
+    try {
+      const run = await subagent.run({
+        sessionKey, message, deliver: false, lane: "clawmem-retitle",
+        idempotencyKey: sha256(`retitle:${uniqueKey}:${text.slice(0, 200)}`),
+        extraSystemPrompt: "You generate accurate, descriptive titles. Output JSON only with a string field title.",
+      });
+      const wait = await subagent.waitForRun({ runId: run.runId, timeoutMs: 30000 });
+      if (wait.status === "timeout" || wait.status === "error") return undefined;
+      const msgs = normalizeMessages((await subagent.getSessionMessages({ sessionKey, limit: 10 })).messages);
+      const raw = [...msgs].reverse().find((e) => e.role === "assistant" && e.text.trim())?.text;
+      if (!raw) return undefined;
+      return parseTitle(raw);
+    } catch (e) {
+      this.api.logger.warn(`clawmem: title generation from text failed (${uniqueKey}): ${String(e)}`);
+      return undefined;
+    } finally {
+      subagent.deleteSession({ sessionKey, deleteTranscript: true }).catch(() => {});
+    }
+  }
+
+  private buildLabels(session: SessionMirrorState, _snapshot: TranscriptSnapshot, _closed: boolean): string[] {
+    const labels = new Set([...DEFAULT_LABELS, "type:conversation", `session:${session.sessionId}`]);
     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 {
+  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],
+      ["summary", summary],
     ]);
   }
 
@@ -172,6 +320,7 @@ export class ConversationMirror {
   private resetIssueBinding(session: SessionMirrorState): void {
     session.issueNumber = undefined;
     session.issueTitle = undefined;
+    session.titleSource = undefined;
     session.lastSummaryHash = undefined;
     session.lastMirroredCount = 0;
     session.turnCount = 0;
@@ -184,11 +333,30 @@ function isNotFoundError(error: unknown): boolean {
   const text = String(error);
   return text.includes("HTTP 404");
 }
-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; } }
+/** Derive an initial placeholder title for a new conversation. The real title is generated by LLM once enough messages are available. */
+export function deriveInitialTitle(_messages: NormalizedMessage[], sessionId: string): string {
+  return `${SESSION_TITLE_PREFIX}${sessionId}`;
+}
+
+function parseSummaryAndTitle(raw: string): { summary: string; title?: string } {
+  const tryParse = (s: string): { summary: string; title?: string } | null => {
+    try {
+      const p = JSON.parse(s) as { summary?: unknown; title?: unknown };
+      const summary = typeof p?.summary === "string" && p.summary.trim() ? p.summary.trim() : null;
+      if (!summary) return null;
+      const title = typeof p?.title === "string" && p.title.trim() ? p.title.trim() : undefined;
+      return { summary, title };
+    } 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; title?: unknown };
+          const summary = typeof p?.summary === "string" && p.summary.trim() ? p.summary.trim() : null;
+          if (!summary) return null;
+          const title = typeof p?.title === "string" && p.title.trim() ? p.title.trim() : undefined;
+          return { summary, title };
+        } catch { return null; }
+      }
       return null;
     }
   };
@@ -196,5 +364,29 @@ function parseSummary(raw: string): string {
   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;
+  return { summary: t };
+}
+
+function parseTitle(raw: string): string | undefined {
+  const tryParse = (s: string): string | undefined => {
+    try {
+      const p = JSON.parse(s) as { title?: unknown };
+      return typeof p?.title === "string" && p.title.trim() ? p.title.trim() : undefined;
+    } catch {
+      const i = s.indexOf("{"), j = s.lastIndexOf("}");
+      if (i >= 0 && j > i) {
+        try {
+          const p = JSON.parse(s.slice(i, j + 1)) as { title?: unknown };
+          return typeof p?.title === "string" && p.title.trim() ? p.title.trim() : undefined;
+        } catch { return undefined; }
+      }
+      return undefined;
+    }
+  };
+  const t = raw.trim();
+  const direct = tryParse(t);
+  if (direct) return direct;
+  const f = /^```(?:json)?\s*([\s\S]*?)```$/i.exec(t);
+  if (f?.[1]) return tryParse(f[1].trim());
+  return undefined;
 }

package/src/github-client.ts

@@ -3,11 +3,18 @@ import { resolveLabelColor, labelDescription, extractLabelNames, isManagedLabel
 import type { AnonymousSessionResponse, ClawMemResolvedRoute } from "./types.js";
 
 type IssueResponse = { number: number; title?: string; body?: string; state?: string; labels?: Array<{ name?: string } | string> };
+type SearchIssuesResponse = { items?: IssueResponse[]; total_count?: number; incomplete_results?: boolean };
+type CommentResponse = { id?: number; body?: string; created_at?: string };
+type LabelResponse = { name?: string; color?: string; description?: string };
 type ReqOpts = { allowNotFound?: boolean; allowValidationError?: boolean; omitAuth?: boolean };
 
 export class GitHubIssueClient {
   constructor(private readonly config: ClawMemResolvedRoute, private readonly log: { warn?: (msg: string) => void }) {}
 
+  repo(): string | undefined {
+    return this.config.repo?.trim() || undefined;
+  }
+
   async createIssue(params: { title: string; body: string; labels: string[] }): Promise<IssueResponse> {
     return this.req<IssueResponse>(this.repoPath("issues"), { method: "POST", body: JSON.stringify(params) });
   }
@@ -20,12 +27,32 @@ export class GitHubIssueClient {
   async createComment(issueNumber: number, body: string): Promise<void> {
     await this.req(this.repoPath(`issues/${issueNumber}/comments`), { method: "POST", body: JSON.stringify({ body }) });
   }
+  async listComments(issueNumber: number, params?: { page?: number; perPage?: number }): Promise<CommentResponse[]> {
+    const q = new URLSearchParams();
+    q.set("page", String(params?.page ?? 1));
+    q.set("per_page", String(params?.perPage ?? 100));
+    return this.req<CommentResponse[]>(`${this.repoPath(`issues/${issueNumber}/comments`)}?${q}`, { method: "GET" });
+  }
   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 searchIssues(query: string, params?: { page?: number; perPage?: number }): Promise<IssueResponse[]> {
+    const q = new URLSearchParams();
+    q.set("q", query);
+    q.set("page", String(params?.page ?? 1));
+    q.set("per_page", String(params?.perPage ?? 100));
+    const res = await this.req<SearchIssuesResponse>(`search/issues?${q}`, { method: "GET" });
+    return Array.isArray(res?.items) ? res.items : [];
+  }
+  async listLabels(params?: { page?: number; perPage?: number }): Promise<LabelResponse[]> {
+    const q = new URLSearchParams();
+    q.set("page", String(params?.page ?? 1));
+    q.set("per_page", String(params?.perPage ?? 100));
+    return this.req<LabelResponse[]>(`${this.repoPath("labels")}?${q}`, { method: "GET" });
+  }
   async ensureLabels(labels: string[]): Promise<void> {
     for (const label of labels) {
       if (!label.trim()) continue;
@@ -38,8 +65,15 @@ export class GitHubIssueClient {
     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 });
+  async getRepoInfo(): Promise<{ description?: string; name?: string }> {
+    return this.req<{ description?: string; name?: string }>(this.repoPath("").replace(/\/$/, ""), { method: "GET" });
+  }
+  async updateRepoDescription(description: string): Promise<void> {
+    await this.req(this.repoPath("").replace(/\/$/, ""), { method: "PATCH", body: JSON.stringify({ description }) });
+  }
+  async createAnonymousSession(locale?: string): Promise<AnonymousSessionResponse> {
+    const body = locale ? JSON.stringify({ locale }) : undefined;
+    return this.req<AnonymousSessionResponse>("anonymous/session", { method: "POST", ...(body ? { body } : {}) }, { omitAuth: true });
   }
 
   private repoPath(suffix: string): string {