pi-mnemoteca 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 gandazgul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# pi-mnemoteca
+
+Pi extension for **local persistent memory** using
+[Mnemoteca](https://github.com/gandazgul/mnemoteca). It gives your AI coding
+agent memory that persists across sessions. It is offline and does not use cloud
+APIs.
+
+## Prerequisites
+
+Install the `mnemoteca` binary first:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/gandazgul/mnemoteca/main/install.sh | sh
+mnemoteca setup
+```
+
+See the [Mnemoteca README](https://github.com/gandazgul/mnemoteca#installation)
+for detailed setup instructions. On first use, Mnemoteca downloads its ML models,
+approximately 500 MB one time.
+
+Make sure the `mnemoteca` binary is in your `PATH`.
+
+## Installation
+
+Install from npm:
+
+```bash
+pi install npm:pi-mnemoteca
+```
+
+Install from a local checkout during development:
+
+```bash
+pi install ./pi-mnemoteca
+```
+
+## Upgrade from pi-mnemosyne
+
+If you already used the old Pi extension, stop Pi agents before you change
+packages.
+
+1. Migrate CLI data first if needed. Use the
+   [Mnemoteca migration guide](https://github.com/gandazgul/mnemoteca/blob/main/docs/migrate-from-mnemosyne.md).
+2. Install the new extension at the same scope where the old extension was
+   installed:
+   ```bash
+   pi install npm:pi-mnemoteca
+   ```
+3. Verify that Pi loads the new extension and that memory tools work:
+   ```bash
+   pi list
+   ```
+   Store and recall a harmless test memory if needed.
+4. Remove the old package at the matching scope:
+   ```bash
+   pi remove npm:pi-mnemosyne
+   ```
+5. Restart Pi agents.
+
+If your old installation was project-local, run the install and remove commands
+from that project. If it was user-level, use the same user-level Pi context. Do
+not keep `pi-mnemoteca` and `pi-mnemosyne` active together for normal use.
+
+Windows users must finish this replacement before restarting Pi agents. There is
+no Windows `mnemosyne` compatibility shim, alias, copied executable, or renamed
+executable.
+
+## Memory tools
+
+The agent-facing tool names stay stable. They describe memory capabilities, not
+product branding.
+
+| Tool | Purpose |
+| --- | --- |
+| `memory_recall` | Search project memory. |
+| `memory_recall_global` | Search global memory. |
+| `memory_store` | Store a project memory. Set `core=true` to tag it as core. |
+| `memory_store_global` | Store a global memory. Set `core=true` to tag it as core. |
+| `memory_delete` | Delete a memory by the numeric document ID shown in recall or list output. |
+
+Project memory uses a collection name derived from the project directory name.
+If that name is empty or `global`, the extension uses `default`.
+
+The project collection is initialized on `session_start`. The global collection
+is created on first use of `mnemoteca add -g` or the equivalent global store
+tool.
+
+## Session behavior
+
+On session start, the extension:
+
+1. Stores the project working directory.
+2. Checks for `.mnemoteca-debug`.
+3. Initializes the project collection with `mnemoteca init`.
+4. Fetches project and global core memories.
+5. Caches the core-memory block.
+
+Before each agent start, including after compaction, the extension appends the
+cached core-memory block and memory-use guidance to the system prompt. Project
+core memories appear before global core memories. If one core-memory query
+fails, the other can still appear.
+
+A non-core store does not invalidate the core cache. A core store and any delete
+operation invalidate it, because the core-tag state can change.
+
+## Debug files
+
+Create `.mnemoteca-debug` in the project directory before session start to enable
+debug output. The extension writes:
+
+- `.mnemoteca-debug.log`
+- `.mnemoteca-debug-prompt.txt`
+
+Debug writes are best effort and do not stop agent execution.
+
+## Commands taught to the agent
+
+- Use `mnemoteca search -f plain [query]` and `mnemoteca search -g -f plain [query]` to search relevant memories.
+- After significant decisions, use `mnemoteca add "memory content"` to save a concise fact. Use `mnemoteca add -g "memory content"` for cross-project preferences.
+- Delete contradicted memories with `mnemoteca delete [memory id]` after storing the updated memory.
+- Mark critical, always-relevant context as core with `-t core`. You can use repeated tags, such as `mnemoteca add "database is sqlite" -t core -t tech-stack`.
+
+## How it works
+
+```text
+session_start
+  ├─ save cwd and derive project collection
+  ├─ mnemoteca init
+  └─ fetch project and global core memories
+
+before_agent_start
+  └─ append cached core memories and guidance
+
+memory tools
+  ├─ mnemoteca search
+  ├─ mnemoteca add [-t core]
+  └─ mnemoteca delete
+```
+
+The extension calls the `mnemoteca` executable with argument arrays. It does not
+own data storage, select databases, or run migrations.

package/index.ts

@@ -0,0 +1,366 @@
+/**
+ * pi-mnemoteca — Local persistent memory for the pi AI agent.
+ *
+ * Gives the agent memory that persists across sessions using Mnemoteca,
+ * a local document store with hybrid search (BM25 + vector similarity).
+ * All ML inference runs locally via ONNX Runtime. No cloud APIs required.
+ *
+ * Features:
+ * - Core memories (tagged `core`) injected into the system prompt at session start
+ * - memory_recall / memory_recall_global tools for on-demand search
+ * - memory_store / memory_store_global tools with optional `core` tagging
+ * - memory_delete tool for removing outdated memories
+ * - Cache invalidation: core memory cache refreshed only when dirty
+ */
+
+import * as path from "node:path";
+import * as fs from "node:fs";
+import type {ExtensionAPI} from "@mariozechner/pi-coding-agent";
+import {Type} from "@sinclair/typebox";
+
+export default function mnemotecaExtension(pi: ExtensionAPI): void {
+	let projectName = "";
+	let projectCwd = "";
+
+	// ── Debug support ────────────────────────────────────────────────
+	let debugEnabled = false;
+	const debugLog: string[] = [];
+
+	function debug(message: string): void {
+		const timestamp = new Date().toISOString();
+		const line = `[${timestamp}] ${message}`;
+		debugLog.push(line);
+		if (debugEnabled) {
+			try {
+				const debugPath = path.join(projectCwd || ".", ".mnemoteca-debug.log");
+				fs.appendFileSync(debugPath, line + "\n", "utf-8");
+			} catch { /* best effort */ }
+		}
+	}
+
+	function writeDebugPrompt(fullPrompt: string): void {
+		if (!debugEnabled) return;
+		try {
+			const debugInfo = [
+				"=== Mnemoteca Debug Info ===",
+				`Timestamp: ${new Date().toISOString()}`,
+				`Project Name: ${projectName}`,
+				`Project CWD: ${projectCwd}`,
+				`Cache Valid: ${cacheValid}`,
+				`Cached Core Block Length: ${cachedCoreBlock.length}`,
+				`Debug Log (last 50 entries):`,
+				...debugLog.slice(-50),
+				"",
+				"=== System Prompt ===",
+				fullPrompt,
+			].join("\n");
+			fs.writeFileSync(
+				path.join(projectCwd, ".mnemoteca-debug-prompt.txt"),
+				debugInfo,
+				"utf-8",
+			);
+		} catch { /* best effort */ }
+	}
+
+	// ── Core memory cache ─────────────────────────────────────────────
+	let cachedCoreBlock = "";
+	let cacheValid = false;
+
+	// ── Helper: execute Mnemoteca CLI ─────────────────────────────────
+
+	async function mnemoteca(...args: string[]): Promise<string> {
+		debug(`exec: mnemoteca ${args.join(" ")}`);
+		try {
+			const result = await pi.exec("mnemoteca", args, { cwd: projectCwd });
+			debug(`exec result: code=${result.code} stdout=${result.stdout.length}bytes stderr=${result.stderr.length}bytes`);
+
+			if (result.code !== 0) {
+				const errMsg = result.stderr.trim() || `mnemoteca ${args[0]} failed (exit ${result.code})`;
+				// Exit code 127 = command not found in shell
+				if (result.code === 127 || errMsg.includes("not found") || errMsg.includes("ENOENT") || errMsg.includes("No such file")) {
+					debug(`ERROR: mnemoteca binary not found`);
+					return "Error: mnemoteca binary not found. Install it: https://github.com/gandazgul/mnemoteca#quick-start";
+				}
+				debug(`ERROR: ${errMsg}`);
+				throw new Error(errMsg);
+			}
+
+			// Mnemoteca writes output to stderr, use whichever has content
+			return result.stdout || result.stderr;
+		} catch (e: unknown) {
+			const msg = e instanceof Error ? e.message : String(e);
+			debug(`CATCH: ${msg}`);
+			if (
+				msg.includes("not found") ||
+				msg.includes("ENOENT") ||
+				msg.includes("No such file")
+			) {
+				return "Error: mnemoteca binary not found. Install it: https://github.com/gandazgul/mnemoteca#quick-start";
+			}
+			throw e;
+		}
+	}
+
+	// ── Helper: fetch and format core memories ────────────────────────
+
+	async function fetchCoreMemories(): Promise<string> {
+		debug(`fetchCoreMemories: projectName=${projectName}, cwd=${projectCwd}`);
+		const sections: string[] = [];
+
+		// Fetch project core memories
+		try {
+			const localCore = await mnemoteca(
+				"list", "--name", projectName, "--tag", "core", "--format", "plain",
+			);
+			const trimmed = localCore.trim();
+			debug(`project core: ${trimmed.length} chars, starts with: ${JSON.stringify(trimmed.substring(0, 80))}`);
+			if (trimmed && !trimmed.startsWith("No documents")) {
+				sections.push(`Project Core Memories (${projectName}):\n\n${trimmed}`);
+			}
+		} catch (e) {
+			debug(`project core error: ${e instanceof Error ? e.message : String(e)}`);
+		}
+
+		// Fetch global core memories
+		try {
+			const globalCore = await mnemoteca(
+				"list", "--global", "--tag", "core", "--format", "plain",
+			);
+			const trimmed = globalCore.trim();
+			debug(`global core: ${trimmed.length} chars, starts with: ${JSON.stringify(trimmed.substring(0, 80))}`);
+			if (trimmed && !trimmed.startsWith("No documents")) {
+				sections.push(`Global Core Memories:\n\n${trimmed}`);
+			}
+		} catch (e) {
+			debug(`global core error: ${e instanceof Error ? e.message : String(e)}`);
+		}
+
+		const memoriesBlock = sections.length > 0
+			? `\n\n${sections.join("\n\n")}`
+			: "";
+
+		return `\n\n${memoriesBlock}
+
+When to use memory:
+- Search memory when past context would help answer the user's request.
+- Store concise summaries of important decisions, preferences, and patterns.
+- Delete outdated memories when new decisions contradict them. Recall results include a document ID in square brackets (e.g. [42]). Pass that numeric ID to memory_delete to remove the memory.
+- Use **core** for facts that should always be in context (project architecture, key conventions, user preferences).
+- Use **global** variants for cross-project preferences (coding style, tool choices).
+- At the end of a session, store any relevant memories for future sessions.`;
+	}
+
+	// ── Helper: refresh cache if needed ───────────────────────────────
+
+	async function ensureCacheValid(): Promise<void> {
+		if (cacheValid) return;
+		cachedCoreBlock = await fetchCoreMemories();
+		cacheValid = true;
+	}
+
+	function invalidateCache(): void {
+		cacheValid = false;
+	}
+
+	// ── Session start: init collection + load core memories ──────────
+
+	pi.on("session_start", async (_event, ctx) => {
+		projectCwd = ctx.cwd;
+
+		// Check for debug flag file
+		try {
+			fs.accessSync(path.join(projectCwd, ".mnemoteca-debug"));
+			debugEnabled = true;
+			// Clear previous debug log file
+			try { fs.writeFileSync(path.join(projectCwd, ".mnemoteca-debug.log"), "", "utf-8"); } catch { /* ok */ }
+		} catch {
+			debugEnabled = false;
+		}
+
+		debug(`session_start: cwd=${projectCwd}, debugEnabled=${debugEnabled}`);
+
+		// Resolve project name from cwd basename
+		const rawName = path.basename(projectCwd);
+		projectName = rawName === "global" ? "default" : (rawName || "default");
+
+		debug(`project: name=${projectName}`);
+
+		// Auto-init the project collection (idempotent)
+		try {
+			await mnemoteca("init", "--name", projectName);
+		} catch (e) {
+			debug(`init error: ${e instanceof Error ? e.message : String(e)}`);
+		}
+
+		// Pre-fetch core memories
+		invalidateCache();
+		await ensureCacheValid();
+		debug(`session_start complete: cacheValid=${cacheValid}, coreBlockLength=${cachedCoreBlock.length}`);
+	});
+
+	// ── Before agent start: inject core memories into system prompt ──
+
+	pi.on("before_agent_start", async (event) => {
+		await ensureCacheValid();
+
+		const fullPrompt = event.systemPrompt + cachedCoreBlock;
+
+		debug(`before_agent_start: systemPrompt=${event.systemPrompt.length}chars, coreBlock=${cachedCoreBlock.length}chars, total=${fullPrompt.length}chars`);
+		writeDebugPrompt(fullPrompt);
+
+		return {
+			systemPrompt: fullPrompt,
+		};
+	});
+
+	// ── Tools ─────────────────────────────────────────────────────────
+
+	pi.registerTool({
+		name: "memory_recall",
+		label: "Memory Recall",
+		description:
+			"Search project memory for relevant context, past decisions, and preferences. Use this at the start of conversations and whenever past context would help.",
+		promptSnippet: "Search project memory for past context and decisions",
+		parameters: Type.Object({
+			query: Type.String({ description: "Semantic search query" }),
+		}),
+
+		async execute(_toolCallId, params) {
+			// Quote the query to prevent SQLite FTS errors with hyphens and special characters
+			const safeQuery = `"${params.query.replaceAll('"', '""')}"`;
+			const result = await mnemoteca(
+				"search", "--name", projectName, "--format", "plain", safeQuery,
+			);
+			return {
+				content: [{ type: "text", text: result.trim() || "No memories found." }],
+				details: undefined,
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "memory_recall_global",
+		label: "Memory Recall Global",
+		description:
+			"Search global memory for cross-project preferences, decisions and patterns.",
+		promptSnippet: "Search global memory for cross-project preferences",
+		parameters: Type.Object({
+			query: Type.String({ description: "Semantic search query" }),
+		}),
+
+		async execute(_toolCallId, params) {
+			const safeQuery = `"${params.query.replaceAll('"', '""')}"`;
+			const result = await mnemoteca(
+				"search", "--global", "--format", "plain", safeQuery,
+			);
+			return {
+				content: [{ type: "text", text: result.trim() || "No global memories found." }],
+				details: undefined,
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "memory_store",
+		label: "Memory Store",
+		description:
+			"Store a project memory: a decision, preference, or important context. One concise concept per memory. Set core=true for critical context that should always be available in every session (use sparingly).",
+		promptSnippet: "Store a project-scoped memory (decision, preference, context)",
+		promptGuidelines: [
+			"Use memory_store to save important decisions, preferences, and context for future sessions.",
+			"Set core=true only for critical, always-relevant context (like project architecture or key conventions). Core memories are injected into every prompt, so keep them lean.",
+		],
+		parameters: Type.Object({
+			content: Type.String({ description: "Concise memory to store" }),
+			core: Type.Optional(Type.Boolean({
+				description: "If true, this memory is always injected into context (like AGENTS.md). Use sparingly.",
+			})),
+		}),
+
+		async execute(_toolCallId, params) {
+			const args = ["add", "--name", projectName];
+			if (params.core) {
+				args.push("--tag", "core");
+			}
+			args.push(params.content);
+
+			const result = await mnemoteca(...args);
+
+			if (params.core) {
+				invalidateCache();
+			}
+
+			return {
+				content: [{ type: "text", text: result.trim() }],
+				details: undefined,
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "memory_store_global",
+		label: "Memory Store Global",
+		description:
+			"Store a cross-project memory: personal preferences, coding style, tool choices. Set core=true for critical cross-project context that should always be available.",
+		promptSnippet: "Store a cross-project memory (coding style, tool choices)",
+		parameters: Type.Object({
+			content: Type.String({ description: "Global memory to store" }),
+			core: Type.Optional(Type.Boolean({
+				description: "If true, this memory is always injected into context. Use sparingly.",
+			})),
+		}),
+
+		async execute(_toolCallId, params) {
+			// Ensure the global collection exists
+			try {
+				await mnemoteca("init", "--global");
+			} catch {
+				// Already exists — fine
+			}
+
+			const args = ["add", "--global"];
+			if (params.core) {
+				args.push("--tag", "core");
+			}
+			args.push(params.content);
+
+			const result = await mnemoteca(...args);
+
+			if (params.core) {
+				invalidateCache();
+			}
+
+			return {
+				content: [{ type: "text", text: result.trim() }],
+				details: undefined,
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "memory_delete",
+		label: "Memory Delete",
+		description:
+			"Delete an outdated or incorrect memory by its document ID (shown in [brackets] in recall/list results).",
+		promptSnippet: "Delete an outdated memory by document ID",
+		promptGuidelines: [
+			"Use memory_delete to remove outdated, incorrect, or superseded memories.",
+			"First call memory_recall to find the memory. The document ID is shown in [brackets] (e.g. [42]) in recall and list results. Pass that numeric ID to memory_delete.",
+		],
+		parameters: Type.Object({
+			id: Type.Number({ description: "Document ID to delete" }),
+		}),
+
+		async execute(_toolCallId, params) {
+			const result = await mnemoteca("delete", String(params.id));
+
+			// Invalidate cache since we don't know if the deleted memory was core
+			invalidateCache();
+
+			return {
+				content: [{ type: "text", text: result.trim() }],
+				details: undefined,
+			};
+		},
+	});
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "pi-mnemoteca",
+  "version": "0.3.0",
+  "type": "module",
+  "description": "Pi extension for local persistent memory using Mnemoteca — offline semantic search, no cloud required",
+  "author": "gandazgul",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gandazgul/pi-mnemoteca.git"
+  },
+  "keywords": [
+    "pi-package",
+    "mnemoteca",
+    "memory",
+    "local",
+    "offline",
+    "semantic-search",
+    "ai",
+    "coding-agent"
+  ],
+  "pi": {
+    "extensions": [
+      "./"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": ">=0.53.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "typescript": "^5.9.3",
+    "tsx": "^4.20.6"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "tsc --noEmit -p tsconfig.test.json && tsx index.test.ts"
+  }
+}