@pi-unipi/memory 0.1.4 → 0.1.6

package/commands.ts

@@ -7,6 +7,8 @@
 
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { MemoryStorage, searchAllProjects, listAllProjects } from "./storage.js";
+import { showMemorySettings } from "./tui/settings-tui.js";
+import { isEmbeddingReady, hasModelChanged, loadEmbeddingConfig } from "./settings.js";
 
 /**
  * Register memory commands.
@@ -175,4 +177,28 @@ For each item, use the memory_store tool to save it with an appropriate title an
       );
     },
   });
+
+  // --- /unipi:memory-settings ---
+  pi.registerCommand("unipi:memory-settings", {
+    description: "Configure embedding provider and model for vector search",
+    handler: async (_args, ctx) => {
+      // Quick status if called with no TUI
+      if (!ctx.hasUI) {
+        const config = loadEmbeddingConfig();
+        const ready = isEmbeddingReady();
+        const migrated = hasModelChanged();
+        ctx.ui.notify(
+          `Embedding: ${ready ? "✓ Ready" : "✗ Not configured"}\n` +
+          `Provider: ${config.provider}\n` +
+          `Model: ${config.model}\n` +
+          `Dimensions: ${config.dimensions}\n` +
+          (migrated ? "⚠ Model changed — re-embed needed" : ""),
+          "info"
+        );
+        return;
+      }
+
+      await showMemorySettings(pi);
+    },
+  });
 }

package/embedding.ts

@@ -1,22 +1,220 @@
 /**
  * @unipi/memory — Embedding generation
  *
- * Placeholder for future embedding support.
- * Currently uses fuzzy text search only.
+ * Primary: OpenRouter API (openai/text-embedding-3-small)
+ * Fallback: fuzzy-only mode (returns null)
+ *
+ * Embedding dimensions default to 384 for sqlite-vec compatibility.
+ * openai/text-embedding-3 supports custom dimensions via API param.
  */
 
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import {
+  loadEmbeddingConfig,
+  getApiKey,
+  markModelUsed,
+  isEmbeddingReady,
+  type EmbeddingConfig,
+} from "./settings.js";
+
+/** Cached config to avoid reading file on every call */
+let cachedConfig: EmbeddingConfig | null = null;
+let lastConfigLoad = 0;
+const CONFIG_CACHE_MS = 30_000; // 30 seconds
+
+function getConfig(): EmbeddingConfig {
+  const now = Date.now();
+  if (!cachedConfig || now - lastConfigLoad > CONFIG_CACHE_MS) {
+    cachedConfig = loadEmbeddingConfig();
+    lastConfigLoad = now;
+  }
+  return cachedConfig;
+}
+
+/** Force refresh config cache */
+export function refreshConfig(): void {
+  cachedConfig = null;
+  lastConfigLoad = 0;
+}
+
 /**
- * Generate an embedding for the given text.
- * Returns null (fuzzy-only mode).
- *
- * Future: Use LLM or local model for embeddings.
+ * Generate an embedding for the given text via OpenRouter API.
+ * Returns null if not configured or on error.
  */
 export async function generateEmbedding(
-  _text: string,
-  _ai?: any
+  text: string,
+  _ai?: ExtensionAPI | any
 ): Promise<Float32Array | null> {
-  // Fuzzy-only mode for now
-  return null;
+  const config = getConfig();
+  const apiKey = getApiKey();
+
+  if (config.provider !== "openrouter" || !apiKey || !config.model) {
+    return null; // Fuzzy-only mode
+  }
+
+  try {
+    const truncated = text.slice(0, 8000); // OpenRouter/OpenAI limit ~8192 tokens
+
+    const body: any = {
+      model: config.model,
+      input: truncated,
+    };
+
+    // openai/text-embedding-3 supports custom dimensions
+    // ada-002 does NOT — only add if not ada
+    if (!config.model.includes("ada-002")) {
+      body.dimensions = config.dimensions;
+    }
+
+    const response = await fetch("https://openrouter.ai/api/v1/embeddings", {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+        "HTTP-Referer": "https://github.com/Neuron-Mr-White/unipi",
+        "X-Title": "unipi-memory",
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(15_000),
+    });
+
+    if (!response.ok) {
+      const errText = await response.text().catch(() => "unknown");
+      console.warn(`[unipi/memory] Embedding API error ${response.status}: ${errText}`);
+      return null;
+    }
+
+    const data = await response.json() as any;
+    const values = data?.data?.[0]?.embedding;
+
+    if (!Array.isArray(values)) {
+      console.warn("[unipi/memory] Unexpected embedding response format");
+      return null;
+    }
+
+    // Convert to Float32Array, truncate to configured dimensions
+    const dims = config.dimensions;
+    const vec = new Float32Array(dims);
+    for (let i = 0; i < Math.min(values.length, dims); i++) {
+      vec[i] = values[i];
+    }
+
+    return vec;
+  } catch (err: any) {
+    if (err?.name === "TimeoutError") {
+      console.warn("[unipi/memory] Embedding API timeout");
+    } else {
+      console.warn("[unipi/memory] Embedding error:", err?.message || err);
+    }
+    return null;
+  }
+}
+
+/**
+ * Generate embeddings for multiple texts in a single API call.
+ * More efficient than calling generateEmbedding() per text.
+ * Returns array of Float32Array (null for failures).
+ */
+export async function generateEmbeddingsBatch(
+  texts: string[],
+  _ai?: ExtensionAPI | any
+): Promise<(Float32Array | null)[]> {
+  const config = getConfig();
+  const apiKey = getApiKey();
+
+  if (config.provider !== "openrouter" || !apiKey || !config.model) {
+    return texts.map(() => null);
+  }
+
+  try {
+    const truncated = texts.map((t) => t.slice(0, 8000));
+
+    const body: any = {
+      model: config.model,
+      input: truncated,
+    };
+
+    if (!config.model.includes("ada-002")) {
+      body.dimensions = config.dimensions;
+    }
+
+    const response = await fetch("https://openrouter.ai/api/v1/embeddings", {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+        "HTTP-Referer": "https://github.com/Neuron-Mr-White/unipi",
+        "X-Title": "unipi-memory",
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(30_000),
+    });
+
+    if (!response.ok) {
+      return texts.map(() => null);
+    }
+
+    const data = await response.json() as any;
+    const dims = config.dimensions;
+
+    return (data?.data || []).map((item: any) => {
+      if (!Array.isArray(item.embedding)) return null;
+      const vec = new Float32Array(dims);
+      for (let i = 0; i < Math.min(item.embedding.length, dims); i++) {
+        vec[i] = item.embedding[i];
+      }
+      return vec;
+    });
+  } catch {
+    return texts.map(() => null);
+  }
+}
+
+/**
+ * Re-embed all memories across all projects.
+ * Returns count of successfully re-embedded memories.
+ */
+export async function reembedAllMemories(pi: ExtensionAPI): Promise<number> {
+  const { getAllProjectDirs, MemoryStorage } = await import("./storage.js");
+  const projectDirs = getAllProjectDirs();
+  let count = 0;
+
+  for (const { name: projectName, dir } of projectDirs) {
+    try {
+      const storage = new MemoryStorage(projectName);
+      storage.init();
+
+      const memories = storage.listAll();
+      if (memories.length === 0) {
+        storage.close();
+        continue;
+      }
+
+      // Load full records
+      const fullRecords = memories
+        .map((m) => storage.getById(m.id))
+        .filter((r): r is NonNullable<typeof r> => r !== null);
+
+      // Generate embeddings in batch
+      const texts = fullRecords.map((r) => `${r.title} ${r.content}`);
+      const embeddings = await generateEmbeddingsBatch(texts, pi);
+
+      // Update records
+      for (let i = 0; i < fullRecords.length; i++) {
+        if (embeddings[i]) {
+          fullRecords[i].embedding = embeddings[i];
+          storage.store(fullRecords[i]);
+          count++;
+        }
+      }
+
+      storage.close();
+    } catch (err) {
+      console.warn(`[unipi/memory] Failed to re-embed project ${projectName}:`, err);
+    }
+  }
+
+  return count;
 }
 
 /**

package/index.ts

@@ -26,8 +26,9 @@ import {
   searchAllProjects,
   listAllProjects,
 } from "./storage.js";
-import { registerMemoryTools, MEMORY_TOOLS } from "./tools.js";
+import { registerMemoryTools, MEMORY_TOOLS, GLOBAL_SEARCH_ALIAS } from "./tools.js";
 import { registerMemoryCommands } from "./commands.js";
+import { isEmbeddingReady, hasModelChanged } from "./settings.js";
 
 /** Package version */
 const VERSION = getPackageVersion(new URL(".", import.meta.url).pathname);
@@ -47,6 +48,10 @@ function getStorage(): MemoryStorage {
 }
 
 export default function (pi: ExtensionAPI) {
+  // Lifecycle state — tracks whether recall/store have happened this session
+  let recallDone = false;
+  let storeDone = false;
+
   // Register skills directory
   const skillsDir = new URL("./skills", import.meta.url).pathname;
   pi.on("resources_discover", async (_event, _ctx) => {
@@ -56,15 +61,24 @@ export default function (pi: ExtensionAPI) {
   });
 
   // Register tools and commands
-  registerMemoryTools(pi, getStorage);
+  registerMemoryTools(pi, getStorage, () => { recallDone = true; storeDone = true; });
   registerMemoryCommands(pi, getStorage);
 
   // Session lifecycle
   pi.on("session_start", async (_event, ctx) => {
+    // Reset lifecycle flags
+    recallDone = false;
+    storeDone = false;
+
     // Initialize project storage
     const projectName = getProjectName(ctx.cwd);
     projectStorage = new MemoryStorage(projectName);
-    projectStorage.init();
+    try {
+      projectStorage.init();
+    } catch (err) {
+      console.warn("[unipi/memory] Failed to initialize storage, running without memory:", (err as any)?.message ?? err);
+      projectStorage = null;
+    }
 
 
     // Announce module
@@ -78,13 +92,14 @@ export default function (pi: ExtensionAPI) {
         "unipi:memory-forget",
         "unipi:global-memory-search",
         "unipi:global-memory-list",
+        "unipi:memory-settings",
       ],
       tools: [
         MEMORY_TOOLS.STORE,
         MEMORY_TOOLS.SEARCH,
         MEMORY_TOOLS.DELETE,
         MEMORY_TOOLS.LIST,
-        MEMORY_TOOLS.GLOBAL_SEARCH,
+        GLOBAL_SEARCH_ALIAS,
         MEMORY_TOOLS.GLOBAL_LIST,
       ],
     });
@@ -117,8 +132,14 @@ export default function (pi: ExtensionAPI) {
             };
           }
 
-          const projectMemories = projectStorage.listAll();
-          const allMemories = listAllProjects();
+          let projectMemories: Array<{ id: string; title: string; type: string }> = [];
+          let allMemories: Array<{ project: string; id: string; title: string; type: string }> = [];
+          try {
+            projectMemories = projectStorage.listAll();
+            allMemories = listAllProjects();
+          } catch (err) {
+            console.warn("[unipi/memory] Failed to list memories for info panel:", err);
+          }
           const uniqueProjects = [...new Set(allMemories.map((m) => m.project))];
 
           // Get 3 most recent memories (sorted by updated DESC in listAll)
@@ -143,62 +164,91 @@ export default function (pi: ExtensionAPI) {
 
     // Show memory status in UI
     if (ctx.hasUI) {
-      const projectCount = projectStorage.listAll().length;
-      const allMemories = listAllProjects();
-      const projectCountAll = allMemories.length;
+      let projectCount = 0;
+      let projectCountAll = 0;
+      try {
+        projectCount = projectStorage?.listAll()?.length ?? 0;
+        projectCountAll = listAllProjects().length;
+      } catch (err) {
+        console.warn("[unipi/memory] Failed to count memories for status:", err);
+      }
+      const vecReady = isEmbeddingReady();
+      const vecIcon = vecReady ? "⚡" : "📝";
       ctx.ui.setStatus(
         "unipi-memory",
-        `🧠 memory ${projectCount}p/${projectCountAll}all`
+        `${vecIcon} memory ${projectCount}p/${projectCountAll}all${hasModelChanged() ? " ⚠" : ""}`
       );
     }
   });
 
-  // Inject memory titles at session start
+  // Inject memory recall reminder at agent start (hidden message, not system prompt)
   pi.on("before_agent_start", async (event, ctx) => {
+    if (recallDone) return;
     if (!projectStorage) return;
 
     const projectName = getProjectName(ctx.cwd);
-    const projectMemories = projectStorage.listAll();
-
-    if (projectMemories.length === 0) {
-      return; // No memories to inject
+    let projectMemories: Array<{ id: string; title: string; type: string }> = [];
+    try {
+      projectMemories = projectStorage.listAll();
+    } catch (err) {
+      console.warn("[unipi/memory] Failed to list memories for recall:", err);
+      recallDone = true; // Skip recall on error
+      return;
     }
 
-    let injection = "\n\n<memory>\n";
-    injection += `Available memories for project "${projectName}":\n\n`;
-
-    // Project memories
-    for (const m of projectMemories) {
-      injection += `- ${m.title}\n`;
+    if (projectMemories.length === 0) {
+      recallDone = true; // Nothing to recall, skip
+      return;
     }
 
-    injection += "\nUse memory_search to retrieve full content. Use memory_store to save new memories.\n";
-    injection += "Use global_memory_search to search across ALL projects.\n";
-    injection += "</memory>";
+    const titleList = projectMemories.slice(0, 20).map(m => `- ${m.title}`).join("\n");
+    const extra = projectMemories.length > 20 ? `\n... and ${projectMemories.length - 20} more` : "";
 
     return {
-      systemPrompt: event.systemPrompt + injection,
+      message: {
+        customType: "unipi-memory-recall-reminder",
+        content: [
+          "## 🧠 Memory System Active",
+          "",
+          `You have ${projectMemories.length} memories stored for project "${projectName}".`,
+          "**BEFORE starting work**, call `memory_search` with relevant keywords to check for existing context.",
+          "",
+          "Available memories:",
+          titleList + extra,
+          "",
+          "**AFTER completing the task**, if you learned something non-obvious,",
+          "call `memory_store` to save it for future sessions.",
+          "",
+          "Guardrails: read max 10 memory results per search. Update existing memories instead of creating duplicates.",
+        ].join("\n"),
+        display: false,
+      },
     };
   });
 
-  // Auto-consolidation on compaction
-  pi.on("session_before_compact", async (event, ctx) => {
-    const { preparation } = event;
+  // After each agent response, remind LLM to save if it hasn't yet
+  pi.on("agent_end", async (_event, _ctx) => {
+    if (storeDone || !recallDone) return;
 
-    // Extract summary text
-    const summary = preparation.previousSummary || "";
-
-    if (!summary || summary.length < 100) {
-      // Summary too short to extract memories from
-      return;
-    }
-
-    // For now, just log that consolidation would happen
-    // Future: Use LLM to extract memories
-    console.log("[unipi/memory] Auto-consolidation triggered, summary length:", summary.length);
+    pi.sendMessage(
+      {
+        customType: "unipi-memory-retro-reminder",
+        content: [
+          "**🧠 Memory reminder:** If you learned something non-obvious in this task,",
+          "call `memory_store` to save it as a memory for future sessions.",
+          "Update existing memories instead of creating duplicates.",
+        ].join(" "),
+        display: false,
+      },
+      {
+        deliverAs: "nextTurn",
+      },
+    );
+  });
 
-    // Don't modify the compaction summary - return unchanged
-    return {};
+  // After compaction, reset recall state so reminder re-injects
+  pi.on("session_compact", async (_event, _ctx) => {
+    recallDone = false;
   });
 
   // Cleanup on shutdown

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/memory",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Persistent cross-session memory with vector search for Pi coding agent",
   "type": "module",
   "license": "MIT",
@@ -36,8 +36,10 @@
     "storage.ts",
     "search.ts",
     "embedding.ts",
+    "settings.ts",
     "tools.ts",
     "commands.ts",
+    "tui/**/*",
     "skills/**/*",
     "README.md"
   ],

package/settings.ts

@@ -0,0 +1,135 @@
+/**
+ * @unipi/memory — Embedding settings
+ *
+ * Manages embedding configuration: provider, model, API key.
+ * Stored in ~/.unipi/memory/config.json
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+/** Embedding provider type */
+export type EmbeddingProvider = "openrouter" | "none";
+
+/** Embedding configuration */
+export interface EmbeddingConfig {
+  /** Provider for embeddings */
+  provider: EmbeddingProvider;
+  /** Model ID (e.g. "openai/text-embedding-3-small") */
+  model: string;
+  /** OpenRouter API key (encrypted or plaintext) */
+  apiKey?: string;
+  /** Embedding dimensions (default 384 for compatibility) */
+  dimensions: number;
+  /** Model that was used to generate existing embeddings */
+  lastModel?: string;
+  /** Whether to show migration warning on startup */
+  suppressMigrationWarning?: boolean;
+}
+
+/** Default configuration */
+const DEFAULT_CONFIG: EmbeddingConfig = {
+  provider: "none",
+  model: "openai/text-embedding-3-small",
+  dimensions: 384,
+  suppressMigrationWarning: false,
+};
+
+/** Known embedding models on OpenRouter */
+export const OPENROUTER_EMBEDDING_MODELS = [
+  {
+    id: "openai/text-embedding-3-small",
+    name: "OpenAI text-embedding-3-small",
+    dimensions: 1536,
+    costPer1k: "$0.00002",
+    description: "Fast, cheap, good quality. Supports custom dimensions.",
+  },
+  {
+    id: "openai/text-embedding-3-large",
+    name: "OpenAI text-embedding-3-large",
+    dimensions: 3072,
+    costPer1k: "$0.00013",
+    description: "Highest quality. Supports custom dimensions.",
+  },
+  {
+    id: "openai/text-embedding-ada-002",
+    name: "OpenAI text-embedding-ada-002 (legacy)",
+    dimensions: 1536,
+    costPer1k: "$0.0001",
+    description: "Legacy model. Does NOT support custom dimensions.",
+  },
+];
+
+/** Get config file path */
+function getConfigPath(): string {
+  return path.join(os.homedir(), ".unipi", "memory", "config.json");
+}
+
+/** Load embedding config */
+export function loadEmbeddingConfig(): EmbeddingConfig {
+  const configPath = getConfigPath();
+  try {
+    if (fs.existsSync(configPath)) {
+      const raw = fs.readFileSync(configPath, "utf-8");
+      const parsed = JSON.parse(raw);
+      return { ...DEFAULT_CONFIG, ...parsed };
+    }
+  } catch {
+    // Ignore parse errors
+  }
+  return { ...DEFAULT_CONFIG };
+}
+
+/** Save embedding config */
+export function saveEmbeddingConfig(config: EmbeddingConfig): void {
+  const configPath = getConfigPath();
+  const dir = path.dirname(configPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
+}
+
+/** Update partial config */
+export function updateEmbeddingConfig(partial: Partial<EmbeddingConfig>): EmbeddingConfig {
+  const config = loadEmbeddingConfig();
+  const updated = { ...config, ...partial };
+  saveEmbeddingConfig(updated);
+  return updated;
+}
+
+/** Check if embeddings are configured and usable */
+export function isEmbeddingReady(): boolean {
+  const config = loadEmbeddingConfig();
+  return config.provider === "openrouter" && !!config.apiKey && !!config.model;
+}
+
+/** Check if model changed since last embedding generation */
+export function hasModelChanged(): boolean {
+  const config = loadEmbeddingConfig();
+  if (!config.lastModel) return false;
+  return config.model !== config.lastModel;
+}
+
+/** Mark current model as the one used for embedding generation */
+export function markModelUsed(): void {
+  updateEmbeddingConfig({ lastModel: loadEmbeddingConfig().model });
+}
+
+/** Get API key from env or config */
+export function getApiKey(): string | undefined {
+  const config = loadEmbeddingConfig();
+  if (config.apiKey) return config.apiKey;
+  return process.env.OPENROUTER_API_KEY || process.env.OPEN_ROUTER_API_KEY;
+}
+
+/** Set API key */
+export function setApiKey(key: string): void {
+  updateEmbeddingConfig({ apiKey: key, provider: "openrouter" });
+}
+
+/** Remove API key and reset provider */
+export function clearApiKey(): void {
+  updateEmbeddingConfig({ apiKey: undefined, provider: "none" });
+}

package/skills/memory/SKILL.md

@@ -9,7 +9,6 @@ allowed-tools:
   - memory_search
   - memory_delete
   - memory_list
-  - global_memory_store
   - global_memory_search
   - global_memory_list
   - read
@@ -87,16 +86,18 @@ memory_list()
 memory_delete(title: "auth_jwt_prefer_refresh_tokens")
 ```
 
-## Project vs Cross-Project Search
+## Search Scope
 
-| Action | Scope | Tools |
-|--------|-------|-------|
+`memory_search` searches ALL projects by default. Use `scope` param to narrow:
+
+| Action | Scope | Tool |
+|--------|-------|------|
 | **Store** | Always project-scoped | `memory_store` |
-| **Search this project** | Current project only | `memory_search` |
-| **Search all projects** | Cross-project | `global_memory_search` |
+| **Search all projects** | Cross-project (default) | `memory_search(query)` or `memory_search(query, scope="all")` |
+| **Search this project** | Current project only | `memory_search(query, scope="project")` |
 | **List all** | Cross-project | `global_memory_list` |
 
-**All memories are project-scoped.** When you store a memory, it belongs to the current project. Use `global_memory_search` to search across ALL projects when looking for past work or user preferences.
+**All memories are project-scoped.** When you store a memory, it belongs to the current project. `memory_search` searches everything by default — no need to call a separate global search.
 
 ## Update-First Principle
 
@@ -108,7 +109,27 @@ memory_delete(title: "auth_jwt_prefer_refresh_tokens")
 
 This prevents memory duplication and keeps memory clean.
 
-## Consolidation
+## Vector Search (Embeddings)
+
+Memory supports vector similarity search via OpenRouter API.
+
+### Setup
+1. Run `/unipi:memory-settings`
+2. Add your OpenRouter API key
+3. Select embedding model (default: `openai/text-embedding-3-small`)
+
+### How it works
+- Embeddings are generated when storing/searching memories
+- Search combines **vector similarity** + **fuzzy text matching** for best results
+- Vector search finds semantically similar memories even without exact keyword matches
+
+### Model compatibility
+⚠ **Different embedding models produce incompatible vectors.**
+If you switch models, existing embeddings won't match new searches.
+Use `/unipi:memory-settings` → "Re-embed All Memories" to fix.
+
+### No API key?
+Falls back to fuzzy text-only search. Still works, just less semantic.
 
 When the user runs `/unipi:memory-consolidate` or during compaction:
 
@@ -149,3 +170,4 @@ You can read these files directly with the `read` tool for full context.
 | Use vague titles | Use specific `<category>_<detail>` format |
 | Store in wrong scope | Project-specific = project scope, universal = global |
 | Forget to update | When context changes, update the memory |
+| Switch embedding models without re-embedding | Re-embed or accept fuzzy-only fallback |

package/storage.ts

@@ -173,6 +173,12 @@ export class MemoryStorage {
 
   /**
    * Initialize the storage (create DB, tables, load extension).
+   *
+   * Uses retry logic to handle concurrent access from multiple Pi sessions,
+   * especially on WSL/Windows filesystem where SQLite locking can be flaky.
+   *
+   * IMPORTANT: We never delete the DB here — another session may have it open.
+   * If all retries fail, we throw and let this session run without memory.
    */
   init(): void {
     // Ensure directory exists
@@ -181,6 +187,51 @@ export class MemoryStorage {
     }
 
     const dbPath = path.join(this.scopeDir, MEMORY_DB_NAME);
+    const maxRetries = 5;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        this.initDb(dbPath);
+        return; // Success
+      } catch (err: any) {
+        const isTransient =
+          err?.message?.includes("disk I/O error") ||
+          err?.code === "SQLITE_IOERR" ||
+          err?.code === "SQLITE_BUSY" ||
+          err?.message?.includes("database is locked");
+
+        this.close();
+
+        if (isTransient && attempt < maxRetries) {
+          // Likely concurrent access — back off and retry.
+          // Do NOT delete the DB: another session may have it open
+          // and deleting open files on WSL/Windows is unsafe.
+          const delayMs = 50 * Math.pow(2, attempt - 1); // 50, 100, 200, 400
+          console.warn(
+            `[unipi/memory] Transient error on attempt ${attempt}/${maxRetries}, retrying in ${delayMs}ms...`
+          );
+          const end = Date.now() + delayMs;
+          while (Date.now() < end) { /* busy wait */ }
+          continue;
+        }
+
+        // Either non-transient error, or retries exhausted.
+        // Log and throw — this session will run without memory.
+        if (isTransient) {
+          console.warn(
+            "[unipi/memory] Could not open database after retries. " +
+            "Another session may have the DB locked. Memory unavailable this session."
+          );
+        }
+        throw err;
+      }
+    }
+  }
+
+  /**
+   * Open database and set up schema. Called by init() with retry logic.
+   */
+  private initDb(dbPath: string): void {
     this.db = new Database(dbPath);
 
     // Enable WAL mode for concurrent reads
@@ -216,6 +267,9 @@ export class MemoryStorage {
     } catch {
       // vec0 table may already exist or sqlite-vec not loaded
     }
+
+    // Verify database is usable
+    this.db.prepare("SELECT 1 FROM memories LIMIT 0").get();
   }
 
   /**
@@ -228,6 +282,37 @@ export class MemoryStorage {
     }
   }
 
+  /**
+   * Remove corrupted database files (db, wal, shm).
+   */
+  private removeCorruptedDb(): void {
+    const dbPath = path.join(this.scopeDir, MEMORY_DB_NAME);
+    const files = [dbPath, `${dbPath}-wal`, `${dbPath}-shm`];
+    for (const file of files) {
+      try {
+        if (fs.existsSync(file)) {
+          fs.unlinkSync(file);
+          console.warn(`[unipi/memory] Removed corrupted file: ${file}`);
+        }
+      } catch {
+        // Ignore removal errors
+      }
+    }
+  }
+
+  /**
+   * Check if database is healthy.
+   */
+  isHealthy(): boolean {
+    if (!this.db) return false;
+    try {
+      this.db.prepare("SELECT 1").get();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
   /**
    * Store or update a memory record.
    */

package/tools.ts

@@ -23,28 +23,34 @@ export const MEMORY_TOOLS = {
   SEARCH: "memory_search",
   DELETE: "memory_delete",
   LIST: "memory_list",
-  GLOBAL_SEARCH: "global_memory_search",
   GLOBAL_LIST: "global_memory_list",
 } as const;
 
+// Keep old name as alias for backward compat
+export const GLOBAL_SEARCH_ALIAS = "global_memory_search";
+
 /**
  * Register memory tools.
+ * @param onActivity - called when recall/store happens (marks lifecycle state)
  */
 export function registerMemoryTools(
   pi: ExtensionAPI,
-  getStorage: () => MemoryStorage
+  getStorage: () => MemoryStorage,
+  onActivity?: () => void
 ): void {
   // --- memory_store tool ---
   pi.registerTool({
     name: MEMORY_TOOLS.STORE,
     label: "Store Memory",
     description:
-      "Store or update a memory for cross-session recall. Use for user preferences, project decisions, code patterns, and conversation summaries.",
+      "IMPORTANT: Call at the END of every non-trivial task to save what you learned. " +
+      "Store or update a memory for cross-session recall — user preferences, project decisions, " +
+      "code patterns, and conversation summaries. Update existing memories instead of creating duplicates.",
     promptSnippet: "Store a memory for cross-session recall.",
     promptGuidelines: [
-      "Use memory_store to remember important user preferences, decisions, patterns, or summaries.",
-      "Memory is scoped to the current project.",
-      "Update existing memories instead of creating duplicates.",
+      "IMPORTANT: Always call memory_store when you learn something non-obvious.",
+      "Search for existing similar memories first — update if found, create if not.",
+      "Memory is scoped to the current project. Use for decisions, preferences, patterns, summaries.",
     ],
     parameters: Type.Object({
       title: Type.String({
@@ -64,6 +70,7 @@ export function registerMemoryTools(
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const storage = getStorage();
+      onActivity?.(); // Mark store as done for lifecycle
 
       // Check if similar memory exists
       const existing = storage.getByTitle(params.title);
@@ -127,63 +134,112 @@ export function registerMemoryTools(
     },
   });
 
-  // --- memory_search tool ---
+  // --- memory_search tool (unified: searches all projects by default) ---
   pi.registerTool({
     name: MEMORY_TOOLS.SEARCH,
     label: "Search Memory",
     description:
-      "Search current project memories by keyword. Returns ranked results with snippets.",
-    promptSnippet: "Search project memories for relevant context.",
+      "IMPORTANT: Call BEFORE starting work to check for existing context. " +
+      "Searches memories by keyword. Searches ALL projects by default — returns results with " +
+      "[project_name] prefix. Use scope='project' to limit to current project only.",
+    promptSnippet: "Search memories for relevant context before starting work.",
     promptGuidelines: [
-      "Use memory_search before making decisions when you suspect past work exists.",
+      "IMPORTANT: Always call memory_search before making decisions when you suspect past work exists.",
+      "Searches all projects by default — no need to call a separate global search.",
       "Search for user preferences when setting up new features.",
       "Search for patterns when implementing similar functionality.",
-      "Use global_memory_search to search across ALL projects.",
     ],
     parameters: Type.Object({
       query: Type.String({ description: "Search query" }),
       limit: Type.Optional(
         Type.Number({ description: "Max results (default 10)", default: 10 })
       ),
+      scope: Type.Optional(
+        Type.String({
+          description: "Search scope: 'all' (default, searches all projects) or 'project' (current project only)",
+          enum: ["all", "project"],
+          default: "all",
+        })
+      ),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      const storage = getStorage();
+      onActivity?.(); // Mark recall as done for lifecycle
+      const limit = params.limit || 10;
+      const scope = (params as any).scope || "all";
+
+      if (scope === "project") {
+        // Project-only search (original behavior)
+        const storage = getStorage();
+        const results = storage.search(params.query, limit);
+
+        if (results.length === 0) {
+          return {
+            content: [{ type: "text", text: `No memories found for: "${params.query}"` }],
+            details: { results: [] },
+          };
+        }
 
-      const embedding = await generateEmbedding(params.query, pi);
+        const output = results
+          .map((r, i) => `${i + 1}. **${r.record.title}** (${r.record.type})\n   ${r.snippet}`)
+          .join("\n\n");
 
-      const results = hybridSearch(
-        storage,
-        params.query,
-        params.limit || 10,
-        embedding
-      );
+        return {
+          content: [{ type: "text", text: `Found ${results.length} memories:\n\n${output}` }],
+          details: { results: results.map((r) => r.record.id) },
+        };
+      }
+
+      // Default: search ALL projects
+      const results = searchAllProjects(params.query, limit);
 
       if (results.length === 0) {
         return {
-          content: [
-            {
-              type: "text",
-              text: `No memories found for: "${params.query}"`,
-            },
-          ],
+          content: [{ type: "text", text: `No memories found across projects for: "${params.query}"` }],
           details: { results: [] },
         };
       }
 
       const output = results
-        .map(
-          (r, i) =>
-            `${i + 1}. **${r.record.title}** (${r.record.type})\n   ${r.snippet}`
-        )
+        .map((r, i) => `${i + 1}. [${r.record.project}] **${r.record.title}** (${r.record.type})\n   ${r.snippet}`)
         .join("\n\n");
 
       return {
-        content: [
-          {
-            type: "text",
-            text: `Found ${results.length} memories:\n\n${output}`,
-          },
-        ],
+        content: [{ type: "text", text: `Found ${results.length} memories across projects:\n\n${output}` }],
+        details: { results: results.map((r) => r.record.id) },
+      };
+    },
+  });
+
+  // --- global_memory_search alias (backward compat, delegates to memory_search) ---
+  pi.registerTool({
+    name: GLOBAL_SEARCH_ALIAS,
+    label: "Search All Projects",
+    description:
+      "Alias for memory_search with scope='all'. Searches memories across ALL projects.",
+    promptSnippet: "Search memories across all projects.",
+    parameters: Type.Object({
+      query: Type.String({ description: "Search query" }),
+      limit: Type.Optional(
+        Type.Number({ description: "Max results (default 10)", default: 10 })
+      ),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate) {
+      onActivity?.();
+      const results = searchAllProjects(params.query, params.limit || 10);
+
+      if (results.length === 0) {
+        return {
+          content: [{ type: "text", text: `No memories found across projects for: "${params.query}"` }],
+          details: { results: [] },
+        };
+      }
+
+      const output = results
+        .map((r, i) => `${i + 1}. [${r.record.project}] **${r.record.title}** (${r.record.type})\n   ${r.snippet}`)
+        .join("\n\n");
+
+      return {
+        content: [{ type: "text", text: `Found ${results.length} memories across projects:\n\n${output}` }],
         details: { results: results.map((r) => r.record.id) },
       };
     },
@@ -257,55 +313,7 @@ export function registerMemoryTools(
     },
   });
 
-  // --- global_memory_search tool ---
-  pi.registerTool({
-    name: MEMORY_TOOLS.GLOBAL_SEARCH,
-    label: "Search All Projects",
-    description: "Search memories across ALL projects. Returns results with project names.",
-    promptSnippet: "Search memories across all projects.",
-    promptGuidelines: [
-      "Use global_memory_search when looking for memories from other projects.",
-      "Returns results with [project_name] prefix to identify source.",
-    ],
-    parameters: Type.Object({
-      query: Type.String({ description: "Search query" }),
-      limit: Type.Optional(
-        Type.Number({ description: "Max results (default 10)", default: 10 })
-      ),
-    }),
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      const results = searchAllProjects(params.query, params.limit || 10);
-
-      if (results.length === 0) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `No memories found across projects for: "${params.query}"`,
-            },
-          ],
-          details: { results: [] },
-        };
-      }
-
-      const output = results
-        .map(
-          (r, i) =>
-            `${i + 1}. [${r.record.project}] **${r.record.title}** (${r.record.type})\n   ${r.snippet}`
-        )
-        .join("\n\n");
 
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Found ${results.length} memories across projects:\n\n${output}`,
-          },
-        ],
-        details: { results: results.map((r) => r.record.id) },
-      };
-    },
-  });
 
   // --- global_memory_list tool ---
   pi.registerTool({

package/tui/settings-tui.ts

@@ -0,0 +1,301 @@
+/**
+ * @unipi/memory — Settings TUI
+ *
+ * Interactive settings dialog for embedding configuration.
+ * Uses pi's UI primitives (select, input, notify).
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import {
+  loadEmbeddingConfig,
+  saveEmbeddingConfig,
+  setApiKey,
+  clearApiKey,
+  getApiKey,
+  isEmbeddingReady,
+  hasModelChanged,
+  markModelUsed,
+  OPENROUTER_EMBEDDING_MODELS,
+  type EmbeddingConfig,
+} from "../settings.js";
+
+/** pi.ui type that's available when TUI is present */
+type PiUI = {
+  select: (opts: { title: string; message: string; options: Array<{ label: string; value: string; description?: string }> }) => Promise<string | null | undefined>;
+  input: (opts: { title: string; message: string; placeholder?: string; validate?: (value: string) => Promise<string | null> }) => Promise<string | null | undefined>;
+  notify: (opts: { message: string; level: string }) => Promise<void>;
+};
+
+/**
+ * Show memory settings dialog.
+ * Main entry point for /unipi:memory-settings command.
+ */
+export async function showMemorySettings(pi: ExtensionAPI): Promise<void> {
+  // Cast to access pi.ui which exists at runtime but isn't typed
+  const ui = (pi as any).ui as PiUI;
+  let running = true;
+
+  while (running) {
+    const config = loadEmbeddingConfig();
+    const hasKey = !!getApiKey();
+    const ready = isEmbeddingReady();
+
+    // Build status lines
+    const statusLines = [
+      `Provider: ${config.provider === "none" ? "None (fuzzy-only)" : "OpenRouter"}`,
+      `Model: ${config.model || "N/A"}`,
+      `Dimensions: ${config.dimensions}`,
+      `API Key: ${hasKey ? "✓ Set" : "✗ Not set"}`,
+      `Status: ${ready ? "✓ Ready" : "⚠ Not configured"}`,
+    ];
+
+    if (hasModelChanged() && !config.suppressMigrationWarning) {
+      statusLines.push("");
+      statusLines.push("⚠ Model changed — old embeddings incompatible.");
+      statusLines.push("  Re-embed to use vector search with new model.");
+    }
+
+    const options = [];
+
+    // API key management
+    if (hasKey) {
+      options.push({
+        label: "🔑 Update API Key",
+        value: "__update_key__",
+        description: "Update your OpenRouter API key",
+      });
+      options.push({
+        label: "🗑️ Remove API Key",
+        value: "__remove_key__",
+        description: "Remove API key and disable vector search",
+      });
+    } else {
+      options.push({
+        label: "🔑 Add API Key",
+        value: "__add_key__",
+        description: "Add OpenRouter API key to enable vector search",
+      });
+    }
+
+    // Model selection
+    options.push({
+      label: `📦 Select Model (current: ${config.model})`,
+      value: "__select_model__",
+      description: "Choose embedding model from OpenRouter",
+    });
+
+    // Dimensions
+    options.push({
+      label: `📐 Dimensions: ${config.dimensions}`,
+      value: "__dimensions__",
+      description: "Embedding dimensions (lower = faster, less storage)",
+    });
+
+    // Re-embed
+    if (ready && hasModelChanged()) {
+      options.push({
+        label: "🔄 Re-embed All Memories",
+        value: "__reembed__",
+        description: "Re-generate all embeddings with current model",
+      });
+    }
+
+    // Suppress warning
+    if (hasModelChanged() && !config.suppressMigrationWarning) {
+      options.push({
+        label: "🔕 Suppress Migration Warning",
+        value: "__suppress__",
+        description: "Hide the model change warning",
+      });
+    }
+
+    options.push({
+      label: "← Back",
+      value: "__exit__",
+      description: "Exit settings",
+    });
+
+    const selected = await ui.select({
+      title: "🧠 Memory Settings",
+      message: statusLines.join("\n"),
+      options,
+    });
+
+    if (!selected || selected === "__exit__") {
+      running = false;
+      continue;
+    }
+
+    switch (selected) {
+      case "__add_key__":
+      case "__update_key__":
+        await handleApiKeyInput(ui);
+        break;
+      case "__remove_key__":
+        clearApiKey();
+        await ui.notify({
+          message: "API key removed. Vector search disabled.",
+          level: "info",
+        });
+        break;
+      case "__select_model__":
+        await handleModelSelection(ui);
+        break;
+      case "__dimensions__":
+        await handleDimensionsInput(ui);
+        break;
+      case "__reembed__":
+        await handleReembed(ui, pi);
+        break;
+      case "__suppress__":
+        const cfg = loadEmbeddingConfig();
+        cfg.suppressMigrationWarning = true;
+        saveEmbeddingConfig(cfg);
+        await ui.notify({
+          message: "Migration warning suppressed.",
+          level: "info",
+        });
+        break;
+    }
+  }
+}
+
+/**
+ * Handle API key input.
+ */
+async function handleApiKeyInput(ui: PiUI): Promise<void> {
+  const key = await ui.input({
+    title: "OpenRouter API Key",
+    message: "Enter your OpenRouter API key (sk-or-v1-...):",
+    placeholder: "sk-or-v1-...",
+    validate: async (value: string) => {
+      if (!value || value.trim().length === 0) {
+        return "API key cannot be empty";
+      }
+      if (!value.startsWith("sk-or-") && !value.startsWith("sk-")) {
+        return "Key should start with sk-or- or sk-";
+      }
+      return null;
+    },
+  });
+
+  if (key) {
+    setApiKey(key.trim());
+    await ui.notify({
+      message: "API key saved. Vector search enabled.",
+      level: "success",
+    });
+  }
+}
+
+/**
+ * Handle model selection.
+ */
+async function handleModelSelection(ui: PiUI): Promise<void> {
+  const config = loadEmbeddingConfig();
+
+  const options = OPENROUTER_EMBEDDING_MODELS.map((m) => ({
+    label: `${m.name}${m.id === config.model ? " ✓" : ""}`,
+    value: m.id,
+    description: `${m.description} (${m.dimensions}d, ~${m.costPer1k}/1k tokens)`,
+  }));
+
+  // Add custom option
+  options.push({
+    label: "✏️ Custom Model ID",
+    value: "__custom__",
+    description: "Enter a custom OpenRouter model ID",
+  });
+
+  const selected = await ui.select({
+    title: "Select Embedding Model",
+    message: "Choose an embedding model. ⚠ Changing model invalidates existing embeddings.",
+    options,
+  });
+
+  if (!selected) return;
+
+  let modelId = selected;
+
+  if (selected === "__custom__") {
+    const custom = await ui.input({
+      title: "Custom Model ID",
+      message: "Enter the OpenRouter model ID:",
+      placeholder: "openai/text-embedding-3-small",
+    });
+    if (!custom) return;
+    modelId = custom.trim();
+  }
+
+  // Find model info for dimensions
+  const modelInfo = OPENROUTER_EMBEDDING_MODELS.find((m) => m.id === modelId);
+  const dimensions = modelInfo?.dimensions ?? 384;
+
+  config.model = modelId;
+  config.dimensions = dimensions;
+  saveEmbeddingConfig(config);
+
+  await ui.notify({
+    message: `Model set to ${modelId} (${dimensions}d).${hasModelChanged() ? " Re-embed existing memories to use new model." : ""}`,
+    level: "success",
+  });
+}
+
+/**
+ * Handle dimensions input.
+ */
+async function handleDimensionsInput(ui: PiUI): Promise<void> {
+  const config = loadEmbeddingConfig();
+
+  const dimStr = await ui.input({
+    title: "Embedding Dimensions",
+    message: `Enter dimensions (default: 384). Lower = faster, less storage.\nNote: openai/text-embedding-3 supports 256-3072.\nada-002 only supports 1536.`,
+    placeholder: "384",
+    validate: async (value: string) => {
+      const num = parseInt(value, 10);
+      if (isNaN(num) || num < 64 || num > 3072) {
+        return "Must be a number between 64 and 3072";
+      }
+      return null;
+    },
+  });
+
+  if (dimStr) {
+    const dims = parseInt(dimStr, 10);
+    config.dimensions = dims;
+    saveEmbeddingConfig(config);
+
+    await ui.notify({
+      message: `Dimensions set to ${dims}. Re-embed existing memories to apply.`,
+      level: "success",
+    });
+  }
+}
+
+/**
+ * Handle re-embedding all memories.
+ * This is a destructive operation — warns user first.
+ */
+async function handleReembed(ui: PiUI, pi: ExtensionAPI): Promise<void> {
+  const confirm = await ui.select({
+    title: "Re-embed All Memories",
+    message: "⚠ This will re-generate ALL embeddings using the current model.\nOld embeddings will be overwritten.\nThis may take a while and costs API calls.",
+    options: [
+      { label: "Yes, re-embed all", value: "yes", description: "Proceed with re-embedding" },
+      { label: "Cancel", value: "no", description: "Abort" },
+    ],
+  });
+
+  if (confirm !== "yes") return;
+
+  // Import here to avoid circular deps
+  const { reembedAllMemories } = await import("../embedding.js");
+  const count = await reembedAllMemories(pi);
+
+  markModelUsed();
+
+  await ui.notify({
+    message: `Re-embedded ${count} memories with current model.`,
+    level: "success",
+  });
+}