@pi-unipi/memory 0.1.0

package/README.md

@@ -0,0 +1,94 @@
+# @unipi/memory
+
+Persistent cross-session memory with vector search for Pi coding agent.
+
+## 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:@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 |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/unipi:memory-process <text>` | Analyze text and store extracted memories |
+| `/unipi:memory-search <term>` | Search project memories |
+| `/unipi:memory-consolidate` | Consolidate session into memory |
+| `/unipi:memory-forget <title>` | Delete a memory by title |
+| `/unipi:global-memory-process <text>` | Analyze text and store to global |
+| `/unipi:global-memory-search <term>` | Search global memories |
+| `/unipi:global-memory-list` | List all global memories |
+
+## Memory File Format
+
+Memories are stored as markdown with YAML frontmatter:
+
+```markdown
+---
+title: auth_jwt_prefer_refresh_tokens
+tags: [auth, jwt, preferences]
+project: my-app
+created: 2026-04-26T10:00:00Z
+updated: 2026-04-26T15:30:00Z
+type: preference
+---
+
+# Auth: Prefer Refresh Tokens
+
+User prefers short-lived access tokens (15min) with long-lived refresh tokens (30d).
+Always implement token rotation on refresh.
+```
+
+## Naming Convention
+
+**Format:** `<most_important>_<less_important>_<lesser>`
+
+Examples:
+- `auth_jwt_prefer_refresh_tokens`
+- `db_postgres_use_connection_pooling`
+- `style_typescript_strict_mode_always`
+
+## Storage Layout
+
+```
+~/.unipi/memory/
+├── global/
+│   ├── memory.db              # Global vector DB
+│   └── *.md                   # Global memory files
+└── <project_name>/
+    ├── memory.db              # Project vector DB
+    └── *.md                   # Project memory files
+```
+
+## Dependencies
+
+- `better-sqlite3` - SQLite database
+- `sqlite-vec` - Vector search extension
+- `js-yaml` - YAML frontmatter parsing
+- `@unipi/core` - Shared utilities

package/commands.ts

@@ -0,0 +1,178 @@
+/**
+ * @unipi/memory — Command registration
+ *
+ * User-facing commands for memory management.
+ * All storage is project-scoped. "Global" commands search across all projects.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { MemoryStorage, searchAllProjects, listAllProjects } from "./storage.js";
+
+/**
+ * Register memory commands.
+ */
+export function registerMemoryCommands(
+  pi: ExtensionAPI,
+  getStorage: () => MemoryStorage
+): void {
+  // --- /unipi:memory-process ---
+  pi.registerCommand("unipi:memory-process", {
+    description: "Analyze text and store extracted memories",
+    handler: async (args, ctx) => {
+      if (!args.trim()) {
+        ctx.ui.notify("Usage: /unipi:memory-process <text to analyze>", "info");
+        return;
+      }
+
+      ctx.ui.notify(
+        "Analyzing text for memories... Use memory_store tool to save.",
+        "info"
+      );
+
+      // Inject instruction for agent to process
+      pi.sendUserMessage(
+        `Analyze the following text and extract any memory-worthy items (user preferences, project decisions, code patterns, conversation summaries). For each item found, use the memory_store tool to save it.\n\nText to analyze:\n${args}`,
+        { deliverAs: "followUp" }
+      );
+    },
+  });
+
+  // --- /unipi:memory-search ---
+  pi.registerCommand("unipi:memory-search", {
+    description: "Search project memories",
+    handler: async (args, ctx) => {
+      if (!args.trim()) {
+        ctx.ui.notify("Usage: /unipi:memory-search <search term>", "info");
+        return;
+      }
+
+      const storage = getStorage();
+      const results = storage.search(args.trim());
+
+      if (results.length === 0) {
+        ctx.ui.notify(`No memories found for: "${args}"`, "info");
+        return;
+      }
+
+      const output = results
+        .map(
+          (r, i) =>
+            `${i + 1}. ${r.record.title} (${r.record.type})\n   ${r.snippet}`
+        )
+        .join("\n\n");
+
+      ctx.ui.notify(
+        `Found ${results.length} memories:\n\n${output}`,
+        "info"
+      );
+    },
+  });
+
+  // --- /unipi:memory-consolidate ---
+  pi.registerCommand("unipi:memory-consolidate", {
+    description: "Consolidate current session into memory",
+    handler: async (args, ctx) => {
+      ctx.ui.notify(
+        "Consolidating session into memory... Use memory_store tool to save insights.",
+        "info"
+      );
+
+      // Inject instruction for agent to consolidate
+      pi.sendUserMessage(
+        `Review the current session and identify any memory-worthy items:
+- User preferences discovered
+- Project decisions made
+- Code patterns learned
+- Important context to remember
+
+For each item, use the memory_store tool to save it with an appropriate title and type.`,
+        { deliverAs: "followUp" }
+      );
+    },
+  });
+
+  // --- /unipi:memory-forget ---
+  pi.registerCommand("unipi:memory-forget", {
+    description: "Delete a memory by title",
+    handler: async (args, ctx) => {
+      if (!args.trim()) {
+        ctx.ui.notify("Usage: /unipi:memory-forget <memory title>", "info");
+        return;
+      }
+
+      const storage = getStorage();
+      const deleted = storage.deleteByTitle(args.trim());
+
+      ctx.ui.notify(
+        deleted
+          ? `Deleted memory: ${args}`
+          : `Memory not found: ${args}`,
+        "info"
+      );
+    },
+  });
+
+  // --- /unipi:global-memory-search ---
+  pi.registerCommand("unipi:global-memory-search", {
+    description: "Search memories across all projects",
+    handler: async (args, ctx) => {
+      if (!args.trim()) {
+        ctx.ui.notify("Usage: /unipi:global-memory-search <search term>", "info");
+        return;
+      }
+
+      const results = searchAllProjects(args.trim());
+
+      if (results.length === 0) {
+        ctx.ui.notify(`No memories found across projects for: "${args}"`, "info");
+        return;
+      }
+
+      const output = results
+        .map(
+          (r, i) =>
+            `${i + 1}. [${r.record.project}] ${r.record.title} (${r.record.type})\n   ${r.snippet}`
+        )
+        .join("\n\n");
+
+      ctx.ui.notify(
+        `Found ${results.length} memories across projects:\n\n${output}`,
+        "info"
+      );
+    },
+  });
+
+  // --- /unipi:global-memory-list ---
+  pi.registerCommand("unipi:global-memory-list", {
+    description: "List all memories across all projects",
+    handler: async (args, ctx) => {
+      const memories = listAllProjects();
+
+      if (memories.length === 0) {
+        ctx.ui.notify("No memories stored in any project.", "info");
+        return;
+      }
+
+      // Group by project
+      const grouped = new Map<string, typeof memories>();
+      for (const m of memories) {
+        const list = grouped.get(m.project) || [];
+        list.push(m);
+        grouped.set(m.project, list);
+      }
+
+      let output = "";
+      for (const [project, projectMemories] of grouped) {
+        output += `\n${project} (${projectMemories.length}):\n`;
+        for (const m of projectMemories) {
+          output += `  - ${m.title} (${m.type})\n`;
+        }
+      }
+
+      ctx.ui.notify(
+        `All memories across ${grouped.size} projects (${memories.length} total):${output}`,
+        "info"
+      );
+    },
+  });
+}

package/embedding.ts

@@ -0,0 +1,46 @@
+/**
+ * @unipi/memory — Embedding generation
+ *
+ * Placeholder for future embedding support.
+ * Currently uses fuzzy text search only.
+ */
+
+/**
+ * Generate an embedding for the given text.
+ * Returns null (fuzzy-only mode).
+ *
+ * Future: Use LLM or local model for embeddings.
+ */
+export async function generateEmbedding(
+  _text: string,
+  _ai?: any
+): Promise<Float32Array | null> {
+  // Fuzzy-only mode for now
+  return null;
+}
+
+/**
+ * Convert Float32Array to Buffer for SQLite storage.
+ */
+export function vectorToBuffer(vec: Float32Array): Buffer {
+  return Buffer.from(vec.buffer);
+}
+
+/**
+ * Convert Buffer from SQLite to Float32Array.
+ */
+export function bufferToVector(buf: Buffer): Float32Array {
+  return new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
+}
+
+/**
+ * Check if embeddings are available (sqlite-vec loaded).
+ */
+export function hasEmbeddings(db: any): boolean {
+  try {
+    db.prepare("SELECT * FROM memories_vec LIMIT 1").get();
+    return true;
+  } catch {
+    return false;
+  }
+}

package/index.ts

@@ -0,0 +1,150 @@
+/**
+ * @unipi/memory — Extension entry
+ *
+ * Persistent cross-session memory with vector search.
+ * All storage is project-scoped. "Global" tools search across all projects.
+ * Injects memory titles at session start.
+ * Auto-consolidates on compaction.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import {
+  UNIPI_EVENTS,
+  MODULES,
+  emitEvent,
+  getPackageVersion,
+} from "@unipi/core";
+import {
+  MemoryStorage,
+  getProjectName,
+  searchAllProjects,
+  listAllProjects,
+} from "./storage.js";
+import { registerMemoryTools, MEMORY_TOOLS } from "./tools.js";
+import { registerMemoryCommands } from "./commands.js";
+
+/** Package version */
+const VERSION = getPackageVersion(new URL(".", import.meta.url).pathname);
+
+/** Storage instance for current project */
+let projectStorage: MemoryStorage | null = null;
+
+/**
+ * Get storage for the current project.
+ */
+function getStorage(): MemoryStorage {
+  if (!projectStorage) {
+    // Fallback: create new instance (shouldn't happen after session_start)
+    return new MemoryStorage("unknown");
+  }
+  return projectStorage;
+}
+
+export default function (pi: ExtensionAPI) {
+  // Register skills directory
+  const skillsDir = new URL("./skills", import.meta.url).pathname;
+  pi.on("resources_discover", async (_event, _ctx) => {
+    return {
+      skillPaths: [skillsDir],
+    };
+  });
+
+  // Register tools and commands
+  registerMemoryTools(pi, getStorage);
+  registerMemoryCommands(pi, getStorage);
+
+  // Session lifecycle
+  pi.on("session_start", async (_event, ctx) => {
+    // Initialize project storage
+    const projectName = getProjectName(ctx.cwd);
+    projectStorage = new MemoryStorage(projectName);
+    projectStorage.init();
+
+    // Announce module
+    emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
+      name: MODULES.MEMORY,
+      version: VERSION,
+      commands: [
+        "unipi:memory-process",
+        "unipi:memory-search",
+        "unipi:memory-consolidate",
+        "unipi:memory-forget",
+        "unipi:global-memory-search",
+        "unipi:global-memory-list",
+      ],
+      tools: [
+        MEMORY_TOOLS.STORE,
+        MEMORY_TOOLS.SEARCH,
+        MEMORY_TOOLS.DELETE,
+        MEMORY_TOOLS.LIST,
+        MEMORY_TOOLS.GLOBAL_SEARCH,
+        MEMORY_TOOLS.GLOBAL_LIST,
+      ],
+    });
+
+    // Show memory status in UI
+    if (ctx.hasUI) {
+      const projectCount = projectStorage.listAll().length;
+      const allMemories = listAllProjects();
+      const projectCountAll = allMemories.length;
+      ctx.ui.setStatus(
+        "unipi-memory",
+        `🧠 memory ${projectCount}p/${projectCountAll}all`
+      );
+    }
+  });
+
+  // Inject memory titles at session start
+  pi.on("before_agent_start", async (event, ctx) => {
+    if (!projectStorage) return;
+
+    const projectName = getProjectName(ctx.cwd);
+    const projectMemories = projectStorage.listAll();
+
+    if (projectMemories.length === 0) {
+      return; // No memories to inject
+    }
+
+    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`;
+    }
+
+    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>";
+
+    return {
+      systemPrompt: event.systemPrompt + injection,
+    };
+  });
+
+  // Auto-consolidation on compaction
+  pi.on("session_before_compact", async (event, ctx) => {
+    const { preparation } = event;
+
+    // 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);
+
+    // Don't modify the compaction summary - return unchanged
+    return {};
+  });
+
+  // Cleanup on shutdown
+  pi.on("session_shutdown", async () => {
+    projectStorage?.close();
+    projectStorage = null;
+  });
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@pi-unipi/memory",
+  "version": "0.1.0",
+  "description": "Persistent cross-session memory with vector search for Pi coding agent",
+  "type": "module",
+  "license": "MIT",
+  "author": "Neuron Mr White",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Neuron-Mr-White/unipi.git",
+    "directory": "packages/memory"
+  },
+  "homepage": "https://github.com/Neuron-Mr-White/unipi#readme",
+  "bugs": {
+    "url": "https://github.com/Neuron-Mr-White/unipi/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "unipi",
+    "memory",
+    "vector-search",
+    "sqlite-vec"
+  ],
+  "pi": {
+    "extensions": ["index.ts"],
+    "skills": ["skills"]
+  },
+  "files": [
+    "index.ts",
+    "storage.ts",
+    "search.ts",
+    "embedding.ts",
+    "tools.ts",
+    "commands.ts",
+    "skills/**/*",
+    "README.md"
+  ],
+  "dependencies": {
+    "better-sqlite3": "^12.9.0",
+    "sqlite-vec": "^0.1.9",
+    "js-yaml": "^4.1.0",
+    "@unipi/core": "*"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/js-yaml": "^4.0.0",
+    "@types/node": "^25.6.0"
+  }
+}

package/search.ts

@@ -0,0 +1,134 @@
+/**
+ * @unipi/memory — Hybrid search algorithm
+ *
+ * Combines vector similarity search with fuzzy text matching
+ * for best recall across semantic and exact matches.
+ */
+
+import type { MemoryStorage, MemoryRecord, SearchResult } from "./storage.js";
+
+/**
+ * Perform hybrid search combining vector + fuzzy.
+ */
+export function hybridSearch(
+  storage: MemoryStorage,
+  query: string,
+  limit = 10,
+  embedding?: Float32Array | null
+): SearchResult[] {
+  // Delegate to storage's search method which already implements hybrid
+  return storage.search(query, limit, embedding);
+}
+
+/**
+ * Calculate fuzzy match score between text and query.
+ * Returns 0-1 score (1 = perfect match).
+ */
+export function fuzzyMatch(text: string, query: string): number {
+  const lowerText = text.toLowerCase();
+  const lowerQuery = query.toLowerCase();
+
+  // Exact match
+  if (lowerText === lowerQuery) return 1.0;
+
+  // Starts with
+  if (lowerText.startsWith(lowerQuery)) return 0.9;
+
+  // Contains
+  if (lowerText.includes(lowerQuery)) return 0.7;
+
+  // Word boundary match
+  const words = lowerQuery.split(/\s+/);
+  let matchedWords = 0;
+  for (const word of words) {
+    if (lowerText.includes(word)) {
+      matchedWords++;
+    }
+  }
+  if (matchedWords > 0) {
+    return 0.3 + (matchedWords / words.length) * 0.4;
+  }
+
+  // Subsequence match
+  let textIdx = 0;
+  let queryIdx = 0;
+  let subsequenceMatches = 0;
+
+  while (textIdx < lowerText.length && queryIdx < lowerQuery.length) {
+    if (lowerText[textIdx] === lowerQuery[queryIdx]) {
+      subsequenceMatches++;
+      queryIdx++;
+    }
+    textIdx++;
+  }
+
+  if (queryIdx === lowerQuery.length) {
+    // All query chars found in order
+    return 0.2 + (subsequenceMatches / lowerQuery.length) * 0.2;
+  }
+
+  return 0;
+}
+
+/**
+ * Extract a snippet around the query match.
+ */
+export function extractSnippet(
+  content: string,
+  query: string,
+  chars = 150
+): string {
+  const lowerContent = content.toLowerCase();
+  const lowerQuery = query.toLowerCase();
+
+  // Find best match position
+  let bestIdx = -1;
+  let bestScore = 0;
+
+  const words = lowerQuery.split(/\s+/);
+  for (const word of words) {
+    const idx = lowerContent.indexOf(word);
+    if (idx !== -1 && (bestIdx === -1 || idx < bestIdx)) {
+      bestIdx = idx;
+      bestScore = 0.8;
+    }
+  }
+
+  if (bestIdx === -1) {
+    // No match, return beginning
+    return content.slice(0, chars) + (content.length > chars ? "..." : "");
+  }
+
+  const start = Math.max(0, bestIdx - chars / 3);
+  const end = Math.min(content.length, bestIdx + chars * 2 / 3);
+  let snippet = content.slice(start, end);
+
+  if (start > 0) snippet = "..." + snippet;
+  if (end < content.length) snippet = snippet + "...";
+
+  return snippet;
+}
+
+/**
+ * Merge and deduplicate search results from multiple sources.
+ */
+export function mergeResults(
+  ...resultSets: SearchResult[][]
+): SearchResult[] {
+  const merged = new Map<string, SearchResult>();
+
+  for (const results of resultSets) {
+    for (const result of results) {
+      const existing = merged.get(result.record.id);
+      if (existing) {
+        // Boost score if found in multiple sources
+        existing.score = Math.min(existing.score + result.score * 0.2, 1);
+      } else {
+        merged.set(result.record.id, { ...result });
+      }
+    }
+  }
+
+  return Array.from(merged.values())
+    .sort((a, b) => b.score - a.score);
+}