@pi-unipi/memory 0.1.13 → 2.0.0

package/README.md

@@ -1,37 +1,8 @@
 # @pi-unipi/memory
 
-Persistent cross-session memory with vector search for Pi coding agent.
+Persistent memory that survives across sessions. Stores facts, preferences, and decisions in SQLite with vector search, so the agent remembers what you told it last week.
 
-## Features
-
-- **Two-tier storage:** SQLite + sqlite-vec for vector search, markdown files for human-readable memory
-- **Project-scoped + global memory:** Each project gets its own DB, global memories accessible cross-project
-- **Hybrid search:** Vector similarity + fuzzy text matching for best recall
-- **Session injection:** Agent sees memory titles at session start
-- **Auto-consolidation:** Memories extracted during compaction
-- **Update-first:** Prevents memory duplication
-
-## Installation
-
-```bash
-# All-in-one (includes memory)
-pi install npm:unipi
-
-# Standalone
-pi install npm:@pi-unipi/memory
-```
-
-## Tools
-
-| Tool | Description |
-|------|-------------|
-| `memory_store` | Store/update memory (project scope) |
-| `memory_search` | Search memories (project scope) |
-| `memory_delete` | Delete memory by ID or title |
-| `memory_list` | List all project memories |
-| `global_memory_store` | Store/update memory (global scope) |
-| `global_memory_search` | Search global memories |
-| `global_memory_list` | List all global memories |
+Two storage tiers: SQLite + sqlite-vec for vector similarity search, markdown files for human-readable memories you can edit by hand. Project-scoped memories stay separate per codebase, global memories are accessible everywhere.
 
 ## Commands
 
@@ -45,9 +16,31 @@ pi install npm:@pi-unipi/memory
 | `/unipi:global-memory-search <term>` | Search global memories |
 | `/unipi:global-memory-list` | List all global memories |
 
-## Memory File Format
+## Special Triggers
+
+At session start, the agent sees memory titles injected into context. This gives it a summary of what it should remember without loading full memory content.
+
+During compaction (if `@pi-unipi/compactor` is installed), memories are auto-extracted from the conversation. The `memory-consolidate` command also triggers this manually.
 
-Memories are stored as markdown with YAML frontmatter:
+Memory registers with the info-screen dashboard, showing project memory count, total count, and consolidation count. The footer subscribes to `MEMORY_STORED`, `MEMORY_DELETED`, and `MEMORYCONSOLIDATED` events to display memory stats.
+
+## Agent Tools
+
+| Tool | Scope | Description |
+|------|-------|-------------|
+| `memory_store` | Project | Store or update a memory |
+| `memory_search` | Project | Search memories by query |
+| `memory_delete` | Project | Delete memory by ID or title |
+| `memory_list` | Project | List all project memories |
+| `global_memory_store` | Global | Store or update global memory |
+| `global_memory_search` | Global | Search global memories |
+| `global_memory_list` | Global | List all global memories |
+
+The agent uses `memory_store` when it learns something worth remembering — a user preference, a technical decision, a code pattern. `memory_search` is used to recall relevant context before answering questions.
+
+## Memory Format
+
+Memories are markdown files with YAML frontmatter:
 
 ```markdown
 ---
@@ -65,16 +58,18 @@ User prefers short-lived access tokens (15min) with long-lived refresh tokens (3
 Always implement token rotation on refresh.
 ```
 
-## Naming Convention
+### Naming Convention
 
-**Format:** `<most_important>_<less_important>_<lesser>`
+Format: `<most_important>_<less_important>_<lesser>`
 
 Examples:
 - `auth_jwt_prefer_refresh_tokens`
 - `db_postgres_use_connection_pooling`
 - `style_typescript_strict_mode_always`
 
-## Storage Layout
+## Configurables
+
+Memory has no configuration file. Storage paths are fixed:
 
 ```
 ~/.unipi/memory/
@@ -88,7 +83,11 @@ Examples:
 
 ## Dependencies
 
-- `better-sqlite3` - SQLite database
-- `sqlite-vec` - Vector search extension
-- `js-yaml` - YAML frontmatter parsing
-- `@pi-unipi/core` - Shared utilities
+- `better-sqlite3` — SQLite database
+- `sqlite-vec` — Vector search extension
+- `js-yaml` — YAML frontmatter parsing
+- `@pi-unipi/core` — Shared utilities
+
+## License
+
+MIT

package/embedding.ts

@@ -55,7 +55,7 @@ export async function generateEmbedding(
   try {
     const truncated = text.slice(0, 8000); // OpenRouter/OpenAI limit ~8192 tokens
 
-    const body: any = {
+    const body: Record<string, unknown> = {
       model: config.model,
       input: truncated,
     };
@@ -99,8 +99,8 @@ export async function generateEmbedding(
     }
 
     return vec;
-  } catch (err: any) {
-    if (err?.name === "TimeoutError") {
+  } catch (err: unknown) {
+    if (err instanceof Error && err.name === "TimeoutError") {
       // Removed console.warn — timeout causes fallback to fuzzy search.
     } else {
       // Removed console.warn — embedding error causes fallback to fuzzy search.
@@ -128,7 +128,7 @@ export async function generateEmbeddingsBatch(
   try {
     const truncated = texts.map((t) => t.slice(0, 8000));
 
-    const body: any = {
+    const body: Record<string, unknown> = {
       model: config.model,
       input: truncated,
     };
@@ -153,10 +153,10 @@ export async function generateEmbeddingsBatch(
       return texts.map(() => null);
     }
 
-    const data = await response.json() as any;
+    const data = await response.json() as { data?: Array<{ embedding?: number[] }> };
     const dims = config.dimensions;
 
-    return (data?.data || []).map((item: any) => {
+    return (data?.data || []).map((item) => {
       if (!Array.isArray(item.embedding)) return null;
       const vec = new Float32Array(dims);
       for (let i = 0; i < Math.min(item.embedding.length, dims); i++) {
@@ -233,7 +233,7 @@ export function bufferToVector(buf: Buffer): Float32Array {
 /**
  * Check if embeddings are available (sqlite-vec loaded).
  */
-export function hasEmbeddings(db: any): boolean {
+export function hasEmbeddings(db: { prepare(sql: string): { get(...args: unknown[]): unknown } }): boolean {
   try {
     db.prepare("SELECT * FROM memories_vec LIMIT 1").get();
     return true;

package/index.ts

@@ -17,8 +17,7 @@ import {
 
 // Get info registry from global (avoids direct import issues with pi's extension loading)
 function getInfoRegistry() {
-  const g = globalThis as any;
-  return g.__unipi_info_registry;
+  return globalThis.__unipi_info_registry;
 }
 import {
   MemoryStorage,
@@ -61,7 +60,10 @@ export default function (pi: ExtensionAPI) {
   });
 
   // Register tools and commands
-  registerMemoryTools(pi, getStorage, () => { recallDone = true; storeDone = true; });
+  registerMemoryTools(pi, getStorage, {
+    onRecall: () => { recallDone = true; },
+    onStore: () => { storeDone = true; },
+  });
   registerMemoryCommands(pi, getStorage);
 
   // Session lifecycle
@@ -186,10 +188,22 @@ export default function (pi: ExtensionAPI) {
   });
 
   // Inject memory recall reminder at agent start (hidden message, not system prompt)
-  pi.on("before_agent_start", async (event, ctx) => {
+  pi.on("before_agent_start", async (_event, ctx) => {
     if (recallDone) return;
     if (!projectStorage) return;
 
+    // Workflow sandboxes and user presets can change the active tool set. Only
+    // instruct the agent to use memory tools that are actually callable now.
+    const activeTools = new Set(pi.getActiveTools());
+    const canSearch = activeTools.has(MEMORY_TOOLS.SEARCH) || activeTools.has(GLOBAL_SEARCH_ALIAS);
+    const canStore = activeTools.has(MEMORY_TOOLS.STORE);
+
+    if (!canSearch && !canStore) {
+      recallDone = true;
+      storeDone = true;
+      return;
+    }
+
     const projectName = getProjectName(ctx.cwd);
     let projectMemories: Array<{ id: string; title: string; type: string }> = [];
     try {
@@ -199,31 +213,49 @@ export default function (pi: ExtensionAPI) {
       return;
     }
 
-    if (projectMemories.length === 0) {
-      recallDone = true; // Nothing to recall, skip
+    if (projectMemories.length === 0 && !canStore) {
+      recallDone = true; // Nothing to recall and no store tool available
       return;
     }
 
-    const titleList = projectMemories.slice(0, 20).map(m => `- ${m.title}`).join("\n");
-    const extra = projectMemories.length > 20 ? `\n... and ${projectMemories.length - 20} more` : "";
+    const lines = [
+      "## 🧠 Memory System Active",
+      "",
+      `You have ${projectMemories.length} memories stored for project "${projectName}".`,
+    ];
+
+    if (canSearch && projectMemories.length > 0) {
+      const titleList = projectMemories.slice(0, 20).map(m => `- ${m.title}`).join("\n");
+      const extra = projectMemories.length > 20 ? `\n... and ${projectMemories.length - 20} more` : "";
+      lines.push(
+        "**BEFORE starting work**, call `memory_search` with relevant keywords to check for existing context.",
+        "",
+        "Available memories:",
+        titleList + extra,
+      );
+    } else {
+      recallDone = true;
+    }
+
+    if (canStore) {
+      lines.push(
+        "",
+        "**AFTER completing the task**, if you learned something non-obvious,",
+        "call `memory_store` to save it for future sessions.",
+      );
+    } else {
+      storeDone = true;
+    }
+
+    lines.push(
+      "",
+      "Guardrails: read max 10 memory results per search. Update existing memories instead of creating duplicates.",
+    );
 
     return {
       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"),
+        content: lines.join("\n"),
         display: false,
       },
     };
@@ -232,6 +264,7 @@ export default function (pi: ExtensionAPI) {
   // After each agent response, remind LLM to save if it hasn't yet
   pi.on("agent_end", async (_event, _ctx) => {
     if (storeDone || !recallDone) return;
+    if (!pi.getActiveTools().includes(MEMORY_TOOLS.STORE)) return;
 
     pi.sendMessage(
       {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/memory",
-  "version": "0.1.13",
+  "version": "2.0.0",
   "description": "Persistent cross-session memory with vector search for Pi coding agent",
   "type": "module",
   "license": "MIT",

package/storage.ts

@@ -13,6 +13,29 @@ import * as path from "node:path";
 import * as os from "node:os";
 import { randomUUID } from "node:crypto";
 
+/** Memory row from SQLite queries */
+interface MemoryRow {
+  id: string;
+  title: string;
+  content?: string;
+  type?: string;
+  project?: string;
+  tags?: string;
+  created?: string;
+  updated?: string;
+  embedding?: { buffer: ArrayBuffer };
+}
+
+/** Search result row from vector queries */
+interface SearchResultRow {
+  id: string;
+  title: string;
+  distance: number;
+  rowid?: number;
+  title_match?: number;
+  content_match?: number;
+}
+
 /** Memory record interface */
 export interface MemoryRecord {
   id: string;
@@ -208,12 +231,14 @@ export class MemoryStorage {
       try {
         this.initDb(dbPath);
         return; // Success
-      } catch (err: any) {
+      } catch (err: unknown) {
+        const errMsg = err instanceof Error ? err.message : "";
+        const errCode = (err instanceof Error && 'code' in err) ? (err as NodeJS.ErrnoException).code : undefined;
         const isTransient =
-          err?.message?.includes("disk I/O error") ||
-          err?.code === "SQLITE_IOERR" ||
-          err?.code === "SQLITE_BUSY" ||
-          err?.message?.includes("database is locked");
+          errMsg.includes("disk I/O error") ||
+          errCode === "SQLITE_IOERR" ||
+          errCode === "SQLITE_BUSY" ||
+          errMsg.includes("database is locked");
 
         this.close();
 
@@ -433,7 +458,7 @@ export class MemoryStorage {
 
     // Get existing IDs from DB
     const existingIds = new Set(
-      (this.db.prepare("SELECT id FROM memories").all() as any[])
+      (this.db.prepare("SELECT id FROM memories").all() as MemoryRow[])
         .map(r => r.id)
     );
 
@@ -494,7 +519,7 @@ export class MemoryStorage {
   findSimilarByTitle(title: string, threshold = 0.6): Array<{ record: MemoryRecord; similarity: number }> {
     if (!this.db) throw new Error("Storage not initialized");
 
-    const allRows = this.db.prepare("SELECT id, title FROM memories").all() as any[];
+    const allRows = this.db.prepare("SELECT id, title FROM memories").all() as MemoryRow[];
     const results: Array<{ record: MemoryRecord; similarity: number }> = [];
 
     const normalizedTitle = title.toLowerCase().replace(/[^a-z0-9]+/g, " ");
@@ -526,18 +551,18 @@ export class MemoryStorage {
   getById(id: string): MemoryRecord | null {
     if (!this.db) throw new Error("Storage not initialized");
 
-    const row = this.db.prepare("SELECT * FROM memories WHERE id = ?").get(id) as any;
+    const row = this.db.prepare("SELECT * FROM memories WHERE id = ?").get(id) as MemoryRow | undefined;
     if (!row) return null;
 
     return {
       id: row.id,
       title: row.title,
-      content: row.content,
+      content: row.content ?? "",
       tags: JSON.parse(row.tags || "[]"),
-      project: row.project,
-      type: row.type,
-      created: row.created,
-      updated: row.updated,
+      project: row.project ?? "",
+      type: (row.type ?? "summary") as MemoryRecord["type"],
+      created: row.created ?? "",
+      updated: row.updated ?? "",
       embedding: row.embedding ? new Float32Array(row.embedding.buffer) : null,
     };
   }
@@ -549,34 +574,34 @@ export class MemoryStorage {
     if (!this.db) throw new Error("Storage not initialized");
 
     // Try exact match first
-    const exact = this.db.prepare("SELECT * FROM memories WHERE title = ?").get(title) as any;
+    const exact = this.db.prepare("SELECT * FROM memories WHERE title = ?").get(title) as MemoryRow | undefined;
     if (exact) {
       return {
         id: exact.id,
         title: exact.title,
-        content: exact.content,
+        content: exact.content ?? "",
         tags: JSON.parse(exact.tags || "[]"),
-        project: exact.project,
-        type: exact.type,
-        created: exact.created,
-        updated: exact.updated,
+        project: exact.project ?? "",
+        type: (exact.type ?? "summary") as MemoryRecord["type"],
+        created: exact.created ?? "",
+        updated: exact.updated ?? "",
         embedding: exact.embedding ? new Float32Array(exact.embedding.buffer) : null,
       };
     }
 
     // Try case-insensitive match
-    const row = this.db.prepare("SELECT * FROM memories WHERE LOWER(title) = LOWER(?)").get(title) as any;
+    const row = this.db.prepare("SELECT * FROM memories WHERE LOWER(title) = LOWER(?)").get(title) as MemoryRow | undefined;
     if (!row) return null;
 
     return {
       id: row.id,
       title: row.title,
-      content: row.content,
+      content: row.content ?? "",
       tags: JSON.parse(row.tags || "[]"),
-      project: row.project,
-      type: row.type,
-      created: row.created,
-      updated: row.updated,
+      project: row.project ?? "",
+      type: (row.type ?? "summary") as MemoryRecord["type"],
+      created: row.created ?? "",
+      updated: row.updated ?? "",
       embedding: row.embedding ? new Float32Array(row.embedding.buffer) : null,
     };
   }
@@ -587,8 +612,8 @@ export class MemoryStorage {
   listAll(): Array<{ id: string; title: string; type: string }> {
     if (!this.db) throw new Error("Storage not initialized");
 
-    const rows = this.db.prepare("SELECT id, title, type FROM memories ORDER BY updated DESC").all() as any[];
-    return rows.map((r) => ({ id: r.id, title: r.title, type: r.type }));
+    const rows = this.db.prepare("SELECT id, title, type FROM memories ORDER BY updated DESC").all() as MemoryRow[];
+    return rows.map((r) => ({ id: r.id, title: r.title, type: r.type ?? "" }));
   }
 
   /**
@@ -647,7 +672,7 @@ export class MemoryStorage {
              ORDER BY distance
              LIMIT ?`
           )
-          .all(Buffer.from(embedding.buffer), limit * 2) as any[];
+          .all(Buffer.from(embedding.buffer), limit * 2) as SearchResultRow[];
 
         for (const vr of vecResults) {
           const memoryId = this.rowidToId(Number(vr.rowid));
@@ -685,11 +710,11 @@ export class MemoryStorage {
         `%${query}%`,
         ...queryWords.flatMap(w => [`%${w}%`, `%${w}%`]),
         limit * 2
-      ) as any[];
+      ) as SearchResultRow[];
 
     for (const fr of fuzzyResults) {
       const existing = results.get(fr.id);
-      const fuzzyScore = (fr.title_match * 0.7 + fr.content_match * 0.3);
+      const fuzzyScore = ((fr.title_match ?? 0) * 0.7 + (fr.content_match ?? 0) * 0.3);
       const record = this.getById(fr.id);
       if (record) {
         const snippet = this.extractSnippet(record.content, query);

package/tools.ts

@@ -29,14 +29,21 @@ export const MEMORY_TOOLS = {
 // Keep old name as alias for backward compat
 export const GLOBAL_SEARCH_ALIAS = "global_memory_search";
 
+export interface MemoryToolActivityCallbacks {
+  /** Called when a recall-style tool is used (search/list). */
+  onRecall?: () => void;
+  /** Called when memory state is changed (store/delete). */
+  onStore?: () => void;
+}
+
 /**
  * Register memory tools.
- * @param onActivity - called when recall/store happens (marks lifecycle state)
+ * @param activity - callbacks for lifecycle reminders
  */
 export function registerMemoryTools(
   pi: ExtensionAPI,
   getStorage: () => MemoryStorage,
-  onActivity?: () => void
+  activity?: MemoryToolActivityCallbacks
 ): void {
   // --- memory_store tool ---
   pi.registerTool({
@@ -69,8 +76,8 @@ export function registerMemoryTools(
       ),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      activity?.onStore?.(); // Mark store as done for lifecycle
       const storage = getStorage();
-      onActivity?.(); // Mark store as done for lifecycle
 
       // Step 1: Check for exact duplicate
       const existing = storage.getByTitle(params.title);
@@ -224,7 +231,7 @@ export function registerMemoryTools(
       ),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      onActivity?.(); // Mark recall as done for lifecycle
+      activity?.onRecall?.(); // Mark recall as done for lifecycle
       const limit = params.limit || 10;
       const scope = (params as any).scope || "all";
 
@@ -285,7 +292,7 @@ export function registerMemoryTools(
       ),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate) {
-      onActivity?.();
+      activity?.onRecall?.();
       const results = searchAllProjects(params.query, params.limit || 10);
 
       if (results.length === 0) {
@@ -317,6 +324,7 @@ export function registerMemoryTools(
       id: Type.Optional(Type.String({ description: "Memory ID to delete" })),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      activity?.onStore?.();
       const storage = getStorage();
 
       let deleted = false;
@@ -348,6 +356,7 @@ export function registerMemoryTools(
     promptSnippet: "List all project memories.",
     parameters: Type.Object({}),
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      activity?.onRecall?.();
       const storage = getStorage();
       const memories = storage.listAll();
 
@@ -384,6 +393,7 @@ export function registerMemoryTools(
     promptSnippet: "List all memories across projects.",
     parameters: Type.Object({}),
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      activity?.onRecall?.();
       const memories = listAllProjects();
 
       if (memories.length === 0) {