@hienlh/ppm 0.9.49 → 0.9.51

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.9.51] - 2026-04-07
+
+### Added
+- **`ppm bot memory` CLI command**: AI can now save cross-project memories via Bash tool — `ppm bot memory save/list/forget`. Stores to `_global` scope in SQLite, persists across all projects and sessions. GoClaw-inspired pattern (CLI tool, not MCP).
+- **System prompt instructs AI**: AI automatically knows to use `ppm bot memory save` when user asks to remember preferences, change address style, or save facts.
+
+### Changed
+- **/memory, /remember, /forget**: Now always use `_global` project scope (cross-project).
+- **ppmbot-memory tests updated**: Removed stale tests referencing deleted methods (`recall`, `save`, `parseExtractionResponse`, `extractiveMemoryFallback`).
+
+## [0.9.50] - 2026-04-07
+
+### Changed
+- **/sessions redesigned**: Filters by current project, shows pinned sessions first with 📌 icon, displays session titles (not project names), supports pagination via `/sessions 2`. Matches PPM web UI behavior.
+
 ## [0.9.49] - 2026-04-07
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.9.49",
+  "version": "0.9.51",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "MIT",

package/src/cli/commands/bot-cmd.ts

@@ -0,0 +1,96 @@
+import { Command } from "commander";
+
+const C = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+  dim: "\x1b[2m",
+};
+
+/**
+ * `ppm bot memory` CLI — allows AI (via Bash tool) to save/list/forget
+ * cross-project memories in the _global scope of clawbot_memories table.
+ *
+ * Usage from AI:
+ *   ppm bot memory save "User prefers Vietnamese" --category preference
+ *   ppm bot memory list
+ *   ppm bot memory forget "Vietnamese"
+ */
+export function registerBotCommands(program: Command): void {
+  const bot = program.command("bot").description("PPMBot utilities");
+
+  const mem = bot.command("memory").description("Manage cross-project memories");
+
+  mem
+    .command("save <content>")
+    .description("Save a cross-project memory")
+    .option("-c, --category <cat>", "Category: fact|preference|decision|architecture|issue", "fact")
+    .option("-s, --session <id>", "Session ID (optional)")
+    .action(async (content: string, opts: { category: string; session?: string }) => {
+      try {
+        const { PPMBotMemory } = await import("../../services/ppmbot/ppmbot-memory.ts");
+        const memory = new PPMBotMemory();
+        const validCategories = ["fact", "decision", "preference", "architecture", "issue"];
+        const category = validCategories.includes(opts.category) ? opts.category : "fact";
+        const id = memory.saveOne("_global", content, category as any, opts.session);
+        console.log(`${C.green}✓${C.reset} Saved memory #${id} [${category}]: ${content}`);
+      } catch (e) {
+        console.error(`${C.red}✗${C.reset} ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+      }
+    });
+
+  mem
+    .command("list")
+    .description("List active cross-project memories")
+    .option("-l, --limit <n>", "Max results", "30")
+    .option("--json", "Output as JSON")
+    .action(async (opts: { limit: string; json?: boolean }) => {
+      try {
+        const { PPMBotMemory } = await import("../../services/ppmbot/ppmbot-memory.ts");
+        const memory = new PPMBotMemory();
+        const results = memory.getSummary("_global", Number(opts.limit) || 30);
+
+        if (opts.json) {
+          console.log(JSON.stringify(results, null, 2));
+          return;
+        }
+
+        if (results.length === 0) {
+          console.log(`${C.dim}No memories found.${C.reset}`);
+          return;
+        }
+
+        for (const r of results) {
+          const catTag = `${C.cyan}[${r.category}]${C.reset}`;
+          console.log(`  #${r.id} ${catTag} ${r.content}`);
+        }
+        console.log(`\n${C.dim}${results.length} memories${C.reset}`);
+      } catch (e) {
+        console.error(`${C.red}✗${C.reset} ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+      }
+    });
+
+  mem
+    .command("forget <topic>")
+    .description("Delete memories matching a topic (FTS5 search)")
+    .action(async (topic: string) => {
+      try {
+        const { PPMBotMemory } = await import("../../services/ppmbot/ppmbot-memory.ts");
+        const memory = new PPMBotMemory();
+        const deleted = memory.forget("_global", topic);
+        if (deleted > 0) {
+          console.log(`${C.green}✓${C.reset} Deleted ${deleted} memory(s) matching "${topic}"`);
+        } else {
+          console.log(`${C.yellow}No memories matched "${topic}"${C.reset}`);
+        }
+      } catch (e) {
+        console.error(`${C.red}✗${C.reset} ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+      }
+    });
+}

package/src/index.ts

@@ -139,4 +139,7 @@ registerCloudCommands(program);
 const { registerExtCommands } = await import("./cli/commands/ext-cmd.ts");
 registerExtCommands(program);
 
+const { registerBotCommands } = await import("./cli/commands/bot-cmd.ts");
+registerBotCommands(program);
+
 program.parse();

package/src/providers/claude-agent-sdk.ts

@@ -717,6 +717,8 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       let retryCount = 0;
       let rateLimitRetryCount = 0;
       let authRetried = false;
+      /** True after the first init event maps ppmId → sdkId. Prevents retry init events from overwriting the mapping. */
+      let initMappingDone = false;
 
       let hadAnyEvents = false;
       retryLoop: while (true) {
@@ -763,16 +765,22 @@ export class ClaudeAgentSdkProvider implements AIProvider {
           if (subtype === "init") {
             const initMsg = msg as any;
             if (initMsg.session_id && initMsg.session_id !== sessionId) {
-              // Only update sdk_id mapping for brand-new sessions (first message).
-              // For resumed sessions the SDK may create a new session_id, but the
-              // old JSONL (keyed by the original sdk_id) still holds the full
-              // conversation history.  Overwriting the mapping would orphan it.
-              const existingSdkId = getSessionMapping(sessionId);
-              const isFirstMessage = existingSdkId === null || existingSdkId === sessionId;
-              if (isFirstMessage) {
-                setSessionMapping(sessionId, initMsg.session_id, meta.projectName, meta.projectPath);
+              // Only update sdk_id mapping once per session lifecycle.
+              // Retries (auth refresh, rate limit) create new SDK queries that
+              // emit fresh init events — overwriting would orphan the original JSONL.
+              if (!initMappingDone) {
+                const existingSdkId = getSessionMapping(sessionId);
+                const isFirstMapping = existingSdkId === null || existingSdkId === sessionId;
+                if (isFirstMapping) {
+                  setSessionMapping(sessionId, initMsg.session_id, meta.projectName, meta.projectPath);
+                  initMappingDone = true;
+                } else {
+                  // Already mapped to a real SDK id from a previous conversation
+                  initMappingDone = true;
+                  console.log(`[sdk] session=${sessionId} preserving existing mapping → ${existingSdkId}`);
+                }
               } else {
-                console.log(`[sdk] session=${sessionId} ignoring new sdk_id=${initMsg.session_id} to preserve existing mapping → ${existingSdkId}`);
+                console.log(`[sdk] session=${sessionId} ignoring retry init sdk_id=${initMsg.session_id} (mapping already set)`);
               }
               const oldMeta = this.activeSessions.get(sessionId);
               if (oldMeta) {
@@ -816,7 +824,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
                 q.close();
                 const { generator: earlyAuthGen, controller: earlyAuthCtrl } = createMessageChannel();
                 const currentSdkId = getSessionMapping(sessionId);
-                const canResume = currentSdkId && currentSdkId !== sessionId;
+                const canResume = !!currentSdkId;
                 if (!canResume) earlyAuthCtrl.push(firstMsg);
                 const retryOpts = { ...queryOptions, sessionId: undefined, resume: canResume ? currentSdkId : undefined, env: retryEnv };
                 const rq = query({
@@ -844,7 +852,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
                 q.close();
                 const { generator: switchGen, controller: switchCtrl } = createMessageChannel();
                 const currentSdkId = getSessionMapping(sessionId);
-                const canResume = currentSdkId && currentSdkId !== sessionId;
+                const canResume = !!currentSdkId;
                 if (!canResume) switchCtrl.push(firstMsg);
                 const retryOpts = { ...queryOptions, sessionId: undefined, resume: canResume ? currentSdkId : undefined, env: switchEnv };
                 const rq = query({
@@ -995,7 +1003,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
                   q.close();
                   const { generator: authRetryGen, controller: authRetryCtrl } = createMessageChannel();
                   const currentSdkId = getSessionMapping(sessionId);
-                  const canResume = currentSdkId && currentSdkId !== sessionId;
+                  const canResume = !!currentSdkId;
                   if (!canResume) authRetryCtrl.push(firstMsg);
                   const retryOpts = { ...queryOptions, sessionId: undefined, resume: canResume ? currentSdkId : undefined, env: retryEnv };
                   const rq = query({
@@ -1050,7 +1058,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
               const rlRetryEnv = this.buildQueryEnv(meta.projectPath, account);
               const { generator: rlRetryGen, controller: rlRetryCtrl } = createMessageChannel();
               const rlCurrentSdkId = getSessionMapping(sessionId);
-              const rlCanResume = rlCurrentSdkId && rlCurrentSdkId !== sessionId;
+              const rlCanResume = !!rlCurrentSdkId;
               if (!rlCanResume) rlRetryCtrl.push(firstMsg);
               const retryOpts = { ...queryOptions, sessionId: undefined, resume: rlCanResume ? rlCurrentSdkId : undefined, env: rlRetryEnv };
               const rq = query({
@@ -1149,7 +1157,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
                 const rlRetryEnv = this.buildQueryEnv(meta.projectPath, account);
                 const { generator: rlRetryGen, controller: rlRetryCtrl } = createMessageChannel();
                 const rlCurrentSdkId2 = getSessionMapping(sessionId);
-                const rlCanResume2 = rlCurrentSdkId2 && rlCurrentSdkId2 !== sessionId;
+                const rlCanResume2 = !!rlCurrentSdkId2;
                 if (!rlCanResume2) rlRetryCtrl.push(firstMsg);
                 const retryOpts = { ...queryOptions, sessionId: undefined, resume: rlCanResume2 ? rlCurrentSdkId2 : undefined, env: rlRetryEnv };
                 const rq = query({
@@ -1180,7 +1188,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
                     const retryEnv = this.buildQueryEnv(meta.projectPath, refreshedAccount);
                     const { generator: authRetryGen2, controller: authRetryCtrl2 } = createMessageChannel();
                     const authCurrentSdkId2 = getSessionMapping(sessionId);
-                    const authCanResume2 = authCurrentSdkId2 && authCurrentSdkId2 !== sessionId;
+                    const authCanResume2 = !!authCurrentSdkId2;
                     if (!authCanResume2) authRetryCtrl2.push(firstMsg);
                     const retryOpts = { ...queryOptions, sessionId: undefined, resume: authCanResume2 ? authCurrentSdkId2 : undefined, env: retryEnv };
                     const rq = query({

package/src/services/db.service.ts

@@ -486,7 +486,23 @@ export function getSessionProjectPath(ppmId: string): string | null {
   return row?.project_path ?? null;
 }
 
-export function setSessionMapping(ppmId: string, sdkId: string, projectName?: string, projectPath?: string): void {
+/**
+ * Set session mapping. By default, refuses to overwrite an existing real SDK ID
+ * (one that differs from both ppmId and the new sdkId) to prevent orphaning JSONL history.
+ * Pass force=true to override (e.g. session delete + recreate).
+ */
+export function setSessionMapping(ppmId: string, sdkId: string, projectName?: string, projectPath?: string, force = false): void {
+  if (!force) {
+    const existing = getSessionMapping(ppmId);
+    if (existing && existing !== ppmId && existing !== sdkId) {
+      console.warn(`[db] Refusing to overwrite session mapping ${ppmId} → ${existing} with ${sdkId} (use force=true to override)`);
+      // Still update project metadata even when refusing sdk_id overwrite
+      getDb().query(
+        "UPDATE session_map SET project_name = COALESCE(?, session_map.project_name), project_path = COALESCE(?, session_map.project_path) WHERE ppm_id = ?",
+      ).run(projectName ?? null, projectPath ?? null, ppmId);
+      return;
+    }
+  }
   getDb().query(
     "INSERT INTO session_map (ppm_id, sdk_id, project_name, project_path) VALUES (?, ?, ?, ?) ON CONFLICT(ppm_id) DO UPDATE SET sdk_id = excluded.sdk_id, project_name = COALESCE(excluded.project_name, session_map.project_name), project_path = COALESCE(excluded.project_path, session_map.project_path)",
   ).run(ppmId, sdkId, projectName ?? null, projectPath ?? null);

package/src/services/ppmbot/ppmbot-service.ts

@@ -5,6 +5,7 @@ import {
   getPairingByChatId,
   createPairingRequest,
   getSessionTitles,
+  getPinnedSessionIds,
   getApprovedPairedChats,
 } from "../db.service.ts";
 import { PPMBotTelegram } from "./ppmbot-telegram.ts";
@@ -159,7 +160,7 @@ class PPMBotService {
         case "start": await this.cmdStart(chatId); break;
         case "project": await this.cmdProject(chatId, cmd.args); break;
         case "new": await this.cmdNew(chatId); break;
-        case "sessions": await this.cmdSessions(chatId); break;
+        case "sessions": await this.cmdSessions(chatId, cmd.args); break;
         case "resume": await this.cmdResume(chatId, cmd.args); break;
         case "status": await this.cmdStatus(chatId); break;
         case "stop": await this.cmdStop(chatId); break;
@@ -254,29 +255,73 @@ class PPMBotService {
     );
   }
 
-  private async cmdSessions(chatId: string): Promise<void> {
-    const sessions = this.sessions.listRecentSessions(chatId, 10);
-    if (sessions.length === 0) {
-      await this.telegram!.sendMessage(Number(chatId), "No recent sessions.");
+  private async cmdSessions(chatId: string, args: string): Promise<void> {
+    const PAGE_SIZE = 8;
+    const page = Math.max(1, parseInt(args, 10) || 1);
+
+    const active = this.sessions.getActiveSession(chatId);
+    const project = active?.projectName;
+
+    // Fetch all sessions for this chat (enough for pagination)
+    const allSessions = this.sessions.listRecentSessions(chatId, 50);
+    // Filter by current project if one is active
+    const filtered = project
+      ? allSessions.filter((s) => s.project_name === project)
+      : allSessions;
+
+    if (filtered.length === 0) {
+      await this.telegram!.sendMessage(Number(chatId), "No sessions yet. Send a message to start.");
       return;
     }
 
-    // Fetch titles for all sessions
-    const titles = getSessionTitles(sessions.map((s) => s.session_id));
+    // Enrich with titles and pin status
+    const titles = getSessionTitles(filtered.map((s) => s.session_id));
+    const pinnedIds = getPinnedSessionIds();
 
-    let text = "<b>Recent Sessions</b>\n\n";
-    sessions.forEach((s, i) => {
-      const active = s.is_active ? " ⬤" : "";
-      const title = titles[s.session_id]?.replace(/^\[PPM\]\s*/, "") || "";
-      const preview = title ? ` — ${escapeHtml(title.slice(0, 40))}` : "";
+    // Sort: pinned first, then by last_message_at desc
+    const sorted = [...filtered].sort((a, b) => {
+      const aPin = pinnedIds.has(a.session_id) ? 1 : 0;
+      const bPin = pinnedIds.has(b.session_id) ? 1 : 0;
+      if (aPin !== bPin) return bPin - aPin;
+      return b.last_message_at - a.last_message_at;
+    });
+
+    const totalPages = Math.ceil(sorted.length / PAGE_SIZE);
+    const start = (page - 1) * PAGE_SIZE;
+    const pageItems = sorted.slice(start, start + PAGE_SIZE);
+
+    if (pageItems.length === 0) {
+      await this.telegram!.sendMessage(Number(chatId), `No sessions on page ${page}.`);
+      return;
+    }
+
+    const header = project ? escapeHtml(project) : "All Projects";
+    let text = `<b>Sessions — ${header}</b>`;
+    if (totalPages > 1) text += ` <i>(${page}/${totalPages})</i>`;
+    text += "\n\n";
+
+    pageItems.forEach((s, i) => {
+      const pin = pinnedIds.has(s.session_id) ? "📌 " : "";
+      const activeDot = s.is_active ? " ⬤" : "";
+      const rawTitle = titles[s.session_id]?.replace(/^\[PPM\]\s*/, "") || "";
+      const title = rawTitle
+        ? escapeHtml(rawTitle.slice(0, 45))
+        : "<i>untitled</i>";
       const date = new Date(s.last_message_at * 1000).toLocaleString(undefined, {
         month: "short", day: "numeric", hour: "2-digit", minute: "2-digit",
       });
       const sid = s.session_id.slice(0, 8);
-      text += `${i + 1}. <b>${escapeHtml(s.project_name)}</b>${preview}${active}\n`;
+      const num = start + i + 1;
+
+      text += `${pin}${num}. ${title}${activeDot}\n`;
       text += `   <code>${sid}</code> · ${date}\n\n`;
     });
-    text += "Resume: /resume &lt;number&gt;";
+
+    text += "Resume: /resume &lt;n&gt; or /resume &lt;id&gt;";
+    if (totalPages > 1 && page < totalPages) {
+      text += `\nNext: /sessions ${page + 1}`;
+    }
+
     await this.telegram!.sendMessage(Number(chatId), text);
   }
 
@@ -323,14 +368,12 @@ class PPMBotService {
   }
 
   private async cmdMemory(chatId: string): Promise<void> {
-    const active = this.sessions.getActiveSession(chatId);
-    const project = active?.projectName ?? "_global";
-    const memories = this.memory.getSummary(project);
+    const memories = this.memory.getSummary("_global");
     if (memories.length === 0) {
-      await this.telegram!.sendMessage(Number(chatId), "No memories stored for this project.");
+      await this.telegram!.sendMessage(Number(chatId), "No memories stored. Use /remember to add.");
       return;
     }
-    let text = `<b>Memory — ${escapeHtml(project)}</b>\n\n`;
+    let text = "<b>Memory</b> (cross-project)\n\n";
     for (const mem of memories) {
       text += `• [${mem.category}] ${escapeHtml(mem.content)}\n`;
     }
@@ -342,9 +385,7 @@ class PPMBotService {
       await this.telegram!.sendMessage(Number(chatId), "Usage: /forget &lt;topic&gt;");
       return;
     }
-    const active = this.sessions.getActiveSession(chatId);
-    const project = active?.projectName ?? "_global";
-    const count = this.memory.forget(project, args);
+    const count = this.memory.forget("_global", args);
     await this.telegram!.sendMessage(Number(chatId), `Forgot ${count} memor${count === 1 ? "y" : "ies"} ✓`);
   }
 
@@ -354,9 +395,8 @@ class PPMBotService {
       return;
     }
     const active = this.sessions.getActiveSession(chatId);
-    const project = active?.projectName ?? "_global";
-    this.memory.saveOne(project, args, "fact", active?.sessionId);
-    await this.telegram!.sendMessage(Number(chatId), "Remembered ✓");
+    this.memory.saveOne("_global", args, "fact", active?.sessionId);
+    await this.telegram!.sendMessage(Number(chatId), "Remembered ✓ (cross-project)");
   }
 
   private async cmdRestart(chatId: string): Promise<void> {
@@ -427,8 +467,8 @@ class PPMBotService {
 /start — Greeting + list projects
 /project &lt;name&gt; — Switch/list projects
 /new — Fresh session (current project)
-/sessions — List recent sessions
-/resume &lt;n&gt; — Resume session #n
+/sessions [page] — List sessions (current project)
+/resume &lt;n or id&gt; — Resume session
 /status — Current project/session info
 /stop — End current session
 /memory — Show project memories
@@ -495,6 +535,15 @@ class PPMBotService {
         systemPrompt += memorySection;
       }
 
+      // Instruct AI to use CLI for cross-project memory persistence
+      systemPrompt += `\n\n## Cross-Project Memory Tool
+When the user asks you to remember something, change how you address them, or save any preference/fact that should persist across projects and sessions, use the Bash tool to run:
+  ppm bot memory save "<content>" --category <category>
+Categories: preference, fact, decision, architecture, issue
+To list saved memories: ppm bot memory list
+To forget: ppm bot memory forget "<topic>"
+This saves to a global store that persists across all projects and sessions.`;
+
       // Send message to AI (prepend system prompt + memory context)
       const opts: SendMessageOpts = {
         permissionMode: (config?.permission_mode ?? "bypassPermissions") as PermissionMode,