pi-memory-stone 0.1.3 → 0.1.4

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "pi-memory-stone",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "description": "Global pi extension: preserves and retrieves useful memory across pi sessions",
   "license": "MIT",
   "keywords": ["pi-package"],
   "files": [
     "src",
+    "skills/**/*",
     "README.md",
     "LICENSE"
   ],
   "pi": {
-    "extensions": ["./src/index.ts"]
+    "extensions": ["./src/index.ts"],
+    "skills": ["./skills"]
   },
   "scripts": {
     "test": "NODE_OPTIONS='--experimental-sqlite' tsx --test test/*.test.ts",

package/skills/pi-memory-stone/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: pi-memory-stone
+description: Persistent cross-session memory for pi via SQLite+FTS5. Remembers past decisions, preferences, turns, and error resolutions across sessions. Use when recalling context from prior sessions, using memory_search/memory_open/memory_remember/memory_forget tools, troubleshooting memory injection, or when user asks about pi-memory-stone, memory stone, session memory, or remembering context.
+---
+
+# Pi Memory Stone
+
+pi-memory-stone indexes session turns into a searchable SQLite+FTS5 database (`~/.pi/agent/memory/memory.db`) and auto-injects relevant past memories into the system prompt before each agent turn.
+
+**Quick check:** `/memory-status` and `/memory-search <query>`.
+
+## Tools
+
+### `memory_search(query, kind?, scope?, limit?)` — find past context
+
+Use **before** answering questions that may have been addressed in past sessions. FTS5-based: include concrete keywords, not abstract concepts. Use `kind` filter for precision: `"decision"`, `"error_resolution"`, `"preference"`, `"task"`, `"turn_summary"`, `"session_summary"`. Use `scope: "global"` for cross-project recall.
+
+**Examples:** `memory_search("database schema user authentication")`, `memory_search("Next.js build error", kind: "error_resolution")`, `memory_search("deployment workflow", scope: "global")`.
+
+### `memory_open(ref)` — full record by ID
+
+Use when an injection packet or search result references a record ID (e.g., `ref=abc123`). Returns full text and metadata. Only shows records visible in current project.
+
+### `memory_remember(kind, text, scope?, tags?, importance?)` — explicit storage
+
+Use **only when the user explicitly asks** to remember something. Defaults to `scope: "project"`. Use `scope: "global"` only when the user says "for all projects". Auto-downgrades to project scope if text appears to contain secrets, hostnames, or internal details.
+
+### `memory_forget(ref, hard?)` — remove stale/wrong memories
+
+Soft-forget hides from future searches. Hard delete (`hard: true`) requires user confirmation via the `/memory-forget --hard` command.
+
+## Ranking (craft better queries)
+
+Hybrid score: FTS match × kind boost × recency decay × confidence × importance, then sorted descending.
+
+| Factor | Boost | Implication |
+|---|---|---|
+| Same-project | ×1.5 | Current project memories rank highest |
+| Kind: decision | ×1.5 | Decisions and errors surface prominently |
+| Kind: error_resolution | ×1.4 | |
+| Kind: preference | ×1.3 | |
+| Recency | Half-life 7 days | Older memories fade; add time hints to queries |
+| Confidence × Importance | 0.5–1.5× | Explicitly remembered items outrank auto-indexed turns |
+
+Queries include the user's first ~200 chars + basenames of recently touched files. Include filenames when searching for file-specific context.
+
+## Injection modes
+
+| Mode | Behavior |
+|---|---|
+| `auto` (default) | FTS5 search every turn + manual refs. Score threshold: 0.3. Auto-injected refs not re-injected (anti-feedback-loop). |
+| `manual` | Only `/memory-inject` refs. Inject every turn until `/memory-clear-injected`. |
+
+Session override (`/memory-mode`) takes precedence over config. Check: `/memory-status`.
+
+## Session state (per-session, persists across turns)
+
+- **enabled** — toggle via `/memory-on` / `/memory-off`
+- **injectionMode** — `auto` or `manual`, via `/memory-mode`, falls back to config
+- **manualRefs** — via `/memory-inject <ref>`, cleared by `/memory-clear-injected`
+
+## Commands quick reference
+
+| Command | Purpose |
+|---|---|
+| `/memory-status [-v]` | Stats, config, effective mode |
+| `/memory-search <q>` | Search (top 20) |
+| `/memory-open <ref>` | Full record |
+| `/memory-inject <ref>...` | Add manual refs for session |
+| `/memory-clear-injected` | Clear manual refs |
+| `/memory-mode <auto\|manual>` | Override injection mode |
+| `/memory-last` | Last injection packet |
+| `/memory-forget <ref> [--hard]` | Soft/hard delete |
+| `/memory-export [path] [--format json\|md] [--all]` | Portable export |
+| `/memory-import <file> [--preserve-project\|--global]` | Import (default: remap to current project) |
+| `/memory-backup [path]` | Backup SQLite DB |
+| `/memory-on` / `/memory-off` | Enable/disable injection |
+
+## Troubleshooting
+
+| Problem | Likely cause | Fix |
+|---|---|---|
+| No memories injected | Score < 0.3 threshold, manual mode, or `/memory-off` | Lower threshold, `/memory-mode auto`, or `/memory-on` |
+| Cross-project memories missing | `crossProjectEnabled: false` in config | Enable in `.pi/settings.json` or `/memory-inject` manually |
+| Search returns nothing | Keywords don't match FTS5, or record soft_forgotten | Use concrete terms; try `/memory-export --all` to find |
+| Global `memory_remember` refused | Text matched as sensitive | The tool auto-downgrades safely; this is expected |
+
+## Config
+
+`.pi/settings.json` in project root (all fields optional, shown with defaults):
+
+```json
+{ "memory": { "enabled": true, "maxInjectedRecords": 5, "maxInjectedTokens": 1000, "scoreThreshold": 0.3, "crossProjectEnabled": false, "injectionMode": "auto" } }
+```
+
+## Privacy guarantees
+
+- All text redacted before storage: API keys, tokens, passwords, connection strings
+- Sensitive paths never indexed: `.env`, keys, certs, `node_modules`, `.git`, `.ssh`, `.aws`
+- Global scope refused for text containing secret/hostname/internal patterns
+- `memory_open` only shows records visible in current project

package/src/commands/index.ts

@@ -500,6 +500,12 @@ async function handleMemoryForget(args: string, ctx: ExtensionCommandContext): P
       continue;
     }
 
+    const currentProjectId = getProjectId(ctx.cwd);
+    if (record.status !== "active" || !isRecordVisibleInProject(record, currentProjectId)) {
+      ctx.ui.notify(`Memory record ${refId} is not available.`, "warning");
+      continue;
+    }
+
     if (hardFlag) {
       const confirmed = ctx.hasUI
         ? await ctx.ui.confirm(

package/src/db/index.ts

@@ -4,7 +4,7 @@
  */
 
 import { DatabaseSync } from "node:sqlite";
-import { existsSync, mkdirSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { redactSecrets } from "../privacy/index.js";
@@ -41,17 +41,38 @@ export function getDb(): DatabaseSync {
   if (!_db) {
     const dbDir = getDbDir();
     if (!existsSync(dbDir)) {
-      mkdirSync(dbDir, { recursive: true });
+      mkdirSync(dbDir, { recursive: true, mode: 0o700 });
     }
+    hardenPathPermissions(dbDir, 0o700);
     _db = new DatabaseSync(getDbPath());
+    hardenDbFilePermissions();
     _db.exec("PRAGMA journal_mode = WAL");
     _db.exec("PRAGMA busy_timeout = 5000");
     _db.exec("PRAGMA foreign_keys = ON");
     runMigrations(_db);
+    hardenDbFilePermissions();
   }
   return _db;
 }
 
+function hardenPathPermissions(path: string, mode: number): void {
+  try {
+    chmodSync(path, mode);
+  } catch {
+    // Best-effort only: do not make memory unavailable on filesystems that
+    // do not support POSIX permissions.
+  }
+}
+
+export function hardenDbFilePermissions(): void {
+  const dbPath = getDbPath();
+  for (const path of [dbPath, `${dbPath}-wal`, `${dbPath}-shm`]) {
+    if (existsSync(path)) {
+      hardenPathPermissions(path, 0o600);
+    }
+  }
+}
+
 export function closeDb(): void {
   if (_db) {
     try {
@@ -253,6 +274,9 @@ export function upsertRecord(record: {
   const updatedAt = record.updated_at ?? now;
   const scope = record.scope ?? "project";
   const projectId = scope === "global" ? null : (record.project_id ?? null);
+  if (scope === "project" && !projectId) {
+    throw new Error("Project-scoped memory records require a project_id");
+  }
   const redactedText = redactSecrets(record.text);
   const redactedTags = record.tags ? redactSecrets(record.tags) : null;
   const id = recordIdentityHash(redactedText, record.kind, scope, projectId);
@@ -363,6 +387,8 @@ export function searchRecordsFts(
 
   if (!terms) return [];
 
+  const safeLimit = Math.max(1, Math.min(200, Number.isFinite(limit) ? Math.floor(limit) : 20));
+
   const results = db
     .prepare(
       `SELECT r.*, fts.rank as rank
@@ -372,7 +398,7 @@ export function searchRecordsFts(
        ORDER BY rank
        LIMIT ?`
     )
-    .all(terms, limit) as unknown as (RecordRow & { rank: number })[];
+    .all(terms, safeLimit) as unknown as (RecordRow & { rank: number })[];
 
   // Apply post-filters
   return results.filter((r) => {

package/src/portable/index.ts

@@ -2,10 +2,11 @@
  * Portable export/import/backup helpers for memory records.
  */
 
-import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, copyFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, resolve } from "node:path";
-import { getDb, getDbPath, listRecords, upsertRecord, type RecordRow } from "../db/index.js";
+import { getDb, getDbPath, hardenDbFilePermissions, listRecords, upsertRecord, type RecordRow } from "../db/index.js";
 import { SCHEMA_VERSION, RECORD_KINDS, RECORD_SCOPES, RECORD_STATUSES, type RecordKind, type RecordScope, type RecordStatus } from "../db/schema.js";
+import { isSensitiveForGlobalMemory } from "../privacy/index.js";
 
 export type ExportFormat = "json" | "md";
 
@@ -68,8 +69,8 @@ export function exportMemory(format: ExportFormat, includeInactive = false): str
 export function writeMemoryExport(path: string, format: ExportFormat, includeInactive = false): number {
   const payload = buildMemoryExport(includeInactive);
   const content = format === "json" ? JSON.stringify(payload, null, 2) + "\n" : exportMarkdown(payload);
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, content, "utf8");
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, content, { encoding: "utf8", mode: 0o600 });
   return payload.records.length;
 }
 
@@ -94,6 +95,14 @@ export function importMemoryJson(raw: string, options: ImportOptions = {}): Impo
 
     const scope = options.scopeOverride ?? record.scope;
     const projectId = scope === "global" ? null : (options.projectId !== undefined ? options.projectId : record.project_id);
+    if (scope === "project" && !projectId) {
+      result.skipped += 1;
+      continue;
+    }
+    if (scope === "global" && isSensitiveForGlobalMemory(`${record.text}\n${record.tags ?? ""}`)) {
+      result.skipped += 1;
+      continue;
+    }
     const id = upsertRecord({
       kind: record.kind,
       scope,
@@ -117,9 +126,13 @@ export function importMemoryJson(raw: string, options: ImportOptions = {}): Impo
 }
 
 export function backupMemoryDatabase(path: string): void {
-  mkdirSync(dirname(path), { recursive: true });
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
   getDb().exec("PRAGMA wal_checkpoint(TRUNCATE)");
+  hardenDbFilePermissions();
   copyFileSync(getDbPath(), path);
+  try {
+    chmodSync(path, 0o600);
+  } catch {}
 }
 
 export function defaultPortablePath(cwd: string, prefix: string, extension: string): string {

package/src/privacy/index.ts

@@ -27,7 +27,7 @@ const SECRET_PATTERNS: { name: string; regex: RegExp; replacement: SecretReplace
   },
   {
     name: "aws-secret",
-    regex: /(?<=SecretAccessKey[=:]\s*)[A-Za-z0-9/+]{40,}/g,
+    regex: /\b(?:aws[_-]?)?secret[_-]?access[_-]?key\b\s*[=:]\s*['"]?[A-Za-z0-9/+=]{40,}['"]?/gi,
     replacement: "[REDACTED:aws-secret]",
   },
   {
@@ -37,12 +37,12 @@ const SECRET_PATTERNS: { name: string; regex: RegExp; replacement: SecretReplace
   },
   {
     name: "generic-api-key",
-    regex: /(?:api[_-]?key|apikey|api[_-]?secret|secret[_-]?key)[=:]\s*['"]?[A-Za-z0-9_\-.]{16,}['"]?/gi,
+    regex: /\b(?:api[_-]?key|apikey|api[_-]?secret|secret[_-]?key|client[_-]?secret|private[_-]?key|access[_-]?key|auth[_-]?key)\b\s*[=:]\s*['"]?[A-Za-z0-9_\-./+=]{16,}['"]?/gi,
     replacement: "[REDACTED:api-key]",
   },
   {
     name: "secret-assignment",
-    regex: /\b(?:secret|secret[_-]?key)\b\s*[=:]\s*(?:['"][^'"]+['"]|[^\s'"`]+)/gi,
+    regex: /\b(?:secret|secret[_-]?key|client[_-]?secret|app[_-]?secret|webhook[_-]?secret|signing[_-]?secret)\b\s*[=:]\s*(?:['"][^'"]+['"]|[^\s'"`]+)/gi,
     replacement: "[REDACTED:secret]",
   },
   {
@@ -126,6 +126,22 @@ export function redactSecrets(text: string): string {
   return result;
 }
 
+export function isSensitiveForGlobalMemory(text: string): boolean {
+  if (redactSecrets(text) !== text) return true;
+
+  return [
+    // Local/absolute/relative filesystem paths and common repo paths.
+    /(?:^|\s)(?:~|\.|\.\.|[A-Za-z]:)?[/\\][^\s]+/,
+    /\b(?:src|lib|test|tests|packages|apps|docs|config)\/[\w./-]+\b/i,
+    /\b[\w.-]+\.(?:ts|tsx|js|jsx|mjs|cjs|json|yaml|yml|toml|env|db|sqlite|pem|key|crt)\b/i,
+    // Hostnames and network endpoints.
+    /\b(?:localhost|127\.0\.0\.1|0\.0\.0\.0|::1)\b/i,
+    /\b[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+(?::\d{2,5})?\b/i,
+    // Implementation/internal detail markers that should stay project-local.
+    /\b(?:internal|private|implementation detail|class|function|method|module|endpoint|schema|table|column)\b/i,
+  ].some((pattern) => pattern.test(text));
+}
+
 export function isSensitivePath(path: string, extraPatterns: RegExp[] = []): boolean {
   const allPatterns = [...DEFAULT_SENSITIVE_PATHS, ...extraPatterns];
 

package/src/retrieval/index.ts

@@ -23,6 +23,8 @@ const KIND_BOOST: Record<string, number> = {
 // ─── Recency decay ──────────────────────────────────────────────────
 
 const RECENCY_HALF_LIFE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+export const MAX_RETRIEVAL_LIMIT = 20;
+const MAX_CANDIDATE_LIMIT = MAX_RETRIEVAL_LIMIT * 10;
 
 function recencyDecay(createdAt: number): number {
   const age = Date.now() - createdAt;
@@ -72,7 +74,7 @@ export function rankAndFilter(
     // and require explicit cross-project retrieval.
     if (rec.scope === "global") {
       if (!crossProjectEnabled) continue;
-    } else if (rec.project_id && currentProjectId && rec.project_id !== currentProjectId) {
+    } else if (!rec.project_id || !currentProjectId || rec.project_id !== currentProjectId) {
       continue;
     }
 
@@ -121,6 +123,11 @@ export function rankAndFilter(
 
 // ─── Full retrieval pipeline ────────────────────────────────────────
 
+export function normalizeRetrievalLimit(value: unknown, fallback: number): number {
+  const numeric = typeof value === "number" && Number.isFinite(value) ? Math.floor(value) : fallback;
+  return Math.max(1, Math.min(MAX_RETRIEVAL_LIMIT, numeric));
+}
+
 export function retrieve(
   userPrompt: string,
   currentProjectId: string | null,
@@ -133,13 +140,14 @@ export function retrieve(
   },
 ): RankedResult[] {
   const config = getConfig();
-  const limit = opts?.limit ?? config.maxInjectedRecords;
+  const limit = normalizeRetrievalLimit(opts?.limit, config.maxInjectedRecords);
   const crossProject = opts?.crossProjectEnabled ?? config.crossProjectEnabled;
 
   const query = buildSearchQuery(userPrompt, recentFiles);
 
-  // Get more candidates than needed (ranking will filter)
-  const candidates = searchRecordsFts(query, limit * 10, opts?.kindFilter, opts?.scopeFilter);
+  // Get more candidates than needed (ranking will filter), but keep local work bounded.
+  const candidateLimit = Math.min(MAX_CANDIDATE_LIMIT, limit * 10);
+  const candidates = searchRecordsFts(query, candidateLimit, opts?.kindFilter, opts?.scopeFilter);
 
   const ranked = rankAndFilter(candidates, currentProjectId, crossProject);
 

package/src/session-state/index.ts

@@ -67,7 +67,8 @@ export function parseRefArgs(args: string): string[] {
 }
 
 export function isRecordVisibleInProject(record: RecordRow, currentProjectId: string | null): boolean {
-  return record.scope === "global" || record.project_id === null || record.project_id === currentProjectId;
+  if (record.scope === "global") return true;
+  return Boolean(currentProjectId && record.project_id && record.project_id === currentProjectId);
 }
 
 export function manualRecordsToRankedResults(

package/src/tools/index.ts

@@ -6,8 +6,10 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { getRecord, softForgetRecord, upsertRecord } from "../db/index.js";
-import { retrieve, buildInjectionPacket, formatInjectionForLlm } from "../retrieval/index.js";
+import { retrieve, buildInjectionPacket, formatInjectionForLlm, normalizeRetrievalLimit } from "../retrieval/index.js";
 import { getProjectId, getConfig } from "../config/index.js";
+import { isSensitiveForGlobalMemory } from "../privacy/index.js";
+import { isRecordVisibleInProject } from "../session-state/index.js";
 import type { RecordKind, RecordScope } from "../db/schema.js";
 
 export function registerTools(pi: ExtensionAPI): void {
@@ -37,12 +39,12 @@ export function registerTools(pi: ExtensionAPI): void {
         ] as const),
       ),
       scope: Type.Optional(StringEnum(["project", "global"] as const)),
-      limit: Type.Optional(Type.Number({ description: "Max results (default 5)" })),
+      limit: Type.Optional(Type.Number({ description: "Max results (default 5, max 20)", minimum: 1, maximum: 20 })),
     }),
     async execute(toolCallId, params, _signal, _onUpdate, ctx) {
       const projectId = getProjectId(ctx.cwd);
       const config = getConfig(ctx.cwd);
-      const limit = params.limit ?? 5;
+      const limit = normalizeRetrievalLimit(params.limit, 5);
 
       const results = retrieve(params.query, projectId, [], {
         limit,
@@ -102,10 +104,8 @@ export function registerTools(pi: ExtensionAPI): void {
       }
 
       const currentProjectId = getProjectId(ctx.cwd);
-      const visibleInCurrentProject =
-        record.scope === "global" || record.project_id === null || record.project_id === currentProjectId;
 
-      if (record.status !== "active" || !visibleInCurrentProject) {
+      if (record.status !== "active" || !isRecordVisibleInProject(record, currentProjectId)) {
         return {
           content: [{ type: "text", text: `Memory record ${params.ref} is not available.` }],
           details: { ref: params.ref, found: false, unavailable: true },
@@ -168,10 +168,7 @@ export function registerTools(pi: ExtensionAPI): void {
       let scope = params.scope ?? "project";
 
       // Safety: never allow global for implementation details, paths, etc.
-      const isSensitiveForGlobal =
-        /\b(?:password|secret|token|key|\.env|localhost|127\.0\.0\.1|internal|private)\b/i.test(
-          params.text,
-        );
+      const isSensitiveForGlobal = isSensitiveForGlobalMemory(`${params.text}\n${params.tags ?? ""}`);
 
       const downgradedToProject = isSensitiveForGlobal && scope === "global";
       if (downgradedToProject) {
@@ -228,14 +225,22 @@ export function registerTools(pi: ExtensionAPI): void {
         };
       }
 
+      const currentProjectId = getProjectId(ctx.cwd);
+      if (record.status !== "active" || !isRecordVisibleInProject(record, currentProjectId)) {
+        return {
+          content: [{ type: "text", text: `Memory record ${params.ref} is not available.` }],
+          details: { ref: params.ref, found: false, unavailable: true },
+        };
+      }
+
       if (params.hard) {
         // For hard delete via tool, we require the user to explicitly confirm
-        // The tool should note this requires user interaction
+        // The tool should note this requires user interaction without leaking record contents.
         return {
           content: [
             {
               type: "text",
-              text: `Permanent deletion requires explicit confirmation. Please use /memory-forget ${params.ref} --hard to permanently delete this record.\n\nRecord: [${record.kind}] ${record.text.slice(0, 200)}`,
+              text: `Permanent deletion requires explicit confirmation. Please use /memory-forget ${params.ref} --hard to permanently delete this record.`,
             },
           ],
           details: { ref: params.ref, requiresConfirmation: true },