pi-recollect 1.0.0

package/index.ts

@@ -0,0 +1,10 @@
+/**
+ * pi-recall extension entry point.
+ * Delegates all registration to src/extension/register.ts.
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { registerPiMemory } from "./src/extension/register.ts";
+
+export default function (pi: ExtensionAPI): void {
+	registerPiMemory(pi);
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "pi-recollect",
+  "version": "1.0.0",
+  "description": "Persistent memory extension for Pi \u2014 semantic search, knowledge compounding, session continuity",
+  "author": "baphuongna",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "memory",
+    "semantic-search",
+    "knowledge"
+  ],
+  "files": [
+    "*.ts",
+    "src/**/*.ts",
+    "skills/**/*",
+    "README.md",
+    "tsconfig.json",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "npm run typecheck && npm test",
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test --test-concurrency=1 --test-timeout=30000 test/unit/*.test.ts"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.7.0",
+    "typebox": "^1.1.24"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@mariozechner/pi-coding-agent": "^0.65.0",
+    "typescript": "^5.9.3"
+  },
+  "peerDependenciesMeta": {
+    "@mariozechner/pi-coding-agent": {
+      "optional": true
+    }
+  }
+}

package/skills/compound-note/skill.md

@@ -0,0 +1,32 @@
+# compound-note
+
+Knowledge compounding: automatically document solutions, patterns, and decisions.
+
+## When to use
+
+- At session shutdown, pi-recall automatically analyzes the session
+- Manual compound notes can be triggered via memory_store with appropriate categories
+- When you want to explicitly capture a solution for future reference
+
+## How it works
+
+1. Session events (errors, edits, decisions) are tracked automatically
+2. At session shutdown, events are analyzed for patterns
+3. Findings are routed as bug/knowledge/decision solutions
+4. Duplicate solutions are merged; new ones are written to .pi-recall/solutions/
+5. PI_MEMORY.md is updated with the latest summary
+
+## YAML solution format
+
+Solutions are stored in `.pi-recall/solutions/` with YAML frontmatter:
+
+```yaml
+type: bug|knowledge|decision
+title: "..."
+created: YYYY-MM-DD
+---
+problem: |
+  ...
+fix: |
+  ...
+```

package/skills/memory-search/skill.md

@@ -0,0 +1,24 @@
+# memory_search
+
+Search persistent memory for relevant knowledge, solutions, decisions, and patterns.
+
+## When to use
+
+- When you need to recall past solutions to similar problems
+- When looking for project conventions or gotchas
+- When investigating decisions made in previous sessions
+
+## Parameters
+
+- `query` (required): Natural language search query
+- `maxResults`: Maximum results to return (default: 5)
+- `scope`: Filter by "all", "solutions", "decisions", "gotchas", "conventions"
+- `detail`: "compact" (title+score), "medium" (preview), "full" (complete content)
+
+## Examples
+
+```
+memory_search(query="auth token refresh", detail="medium")
+memory_search(query="how to handle errors", scope="gotchas")
+memory_search(query="database choice", scope="decisions")
+```

package/skills/memory-store/skill.md

@@ -0,0 +1,26 @@
+# memory_store
+
+Store knowledge in persistent memory for future sessions.
+
+## When to use
+
+- After discovering an important gotcha or workaround
+- When documenting a project convention
+- After making an architectural decision
+- When capturing a reusable pattern
+
+## Parameters
+
+- `category` (required): "gotcha" | "convention" | "decision" | "pattern" | "architecture"
+- `title` (required): Descriptive title
+- `content` (required): Detailed content
+- `metadata.files`: Related file paths
+- `metadata.tags`: Searchable tags
+- `metadata.severity`: "low" | "medium" | "high" | "critical"
+
+## Examples
+
+```
+memory_store(category="gotcha", title="Token refresh cache bug", content="TokenManager.refresh() must clear cache before setTokens", metadata={severity: "high", tags: ["auth", "cache"]})
+memory_store(category="convention", title="Error handling pattern", content="Use Result<T,E> for all service methods", metadata={tags: ["error-handling", "conventions"]})
+```

package/src/compound/analyzer.ts

@@ -0,0 +1,170 @@
+import * as crypto from "node:crypto";
+import type Database from "better-sqlite3";
+import { getSessionEvents } from "../store/events.ts";
+import { routeSessionFindings, type RoutedFinding } from "./router.ts";
+import { extractBugSolution, extractDecision, extractKnowledge, type Solution } from "./extractor.ts";
+import { findPotentialDuplicates, assessOverlap, shouldDedup, type SolutionForDedup } from "./dedup.ts";
+import { writeSolution } from "./writer.ts";
+import { indexContent } from "../store/fts5-index.ts";
+
+export interface AnalysisResult {
+	solutionsFound: number;
+	solutionsWritten: number;
+	duplicatesMerged: number;
+}
+
+/**
+ * Analyze a session at shutdown time:
+ * 1. Extract findings from session events
+ * 2. Route findings to bug/knowledge/decision types
+ * 3. Dedup against existing solutions
+ * 4. Write new solutions
+ */
+export function analyzeSession(
+	db: Database.Database,
+	cwd: string,
+	sessionId: string,
+	dedupThreshold: number = 0.7,
+): AnalysisResult {
+	const events = getSessionEvents(db, sessionId);
+	if (events.length === 0) return { solutionsFound: 0, solutionsWritten: 0, duplicatesMerged: 0 };
+
+	const findings = routeSessionFindings(events);
+	let solutionsFound = 0;
+	let solutionsWritten = 0;
+	let duplicatesMerged = 0;
+
+	for (const finding of findings) {
+		const solution = extractSolution(finding);
+		if (!solution) continue;
+		solutionsFound++;
+
+		const title = buildTitle(finding, finding.events);
+		const solForDedup: SolutionForDedup = {
+			title,
+			content: solutionContent(solution),
+			files: solution.files,
+			tags: solution.tags,
+		};
+
+		// Check for duplicates
+		const dupes = findPotentialDuplicates(db, title);
+		let isDuplicate = false;
+		for (const dupe of dupes) {
+			const dupeForCompare: SolutionForDedup = {
+				title: dupe.title,
+				content: dupe.content,
+				files: dupe.files ? JSON.parse(dupe.files) as string[] : [],
+				tags: dupe.tags ? JSON.parse(dupe.tags) as string[] : [],
+			};
+			const overlap = assessOverlap(solForDedup, dupeForCompare);
+			if (shouldDedup(overlap, dedupThreshold)) {
+				isDuplicate = true;
+				duplicatesMerged++;
+				// Increment access count on the existing solution
+				db.prepare(
+					`UPDATE solutions SET access_count = access_count + 1, last_accessed_at = ? WHERE title = ?`,
+				).run(new Date().toISOString(), dupe.title);
+				break;
+			}
+		}
+
+		if (!isDuplicate) {
+			writeSolutionToDb(db, title, solution);
+			writeSolution(cwd, solution, title);
+			solutionsWritten++;
+		}
+	}
+
+	return { solutionsFound, solutionsWritten, duplicatesMerged };
+}
+
+function extractSolution(finding: RoutedFinding): Solution | null {
+	const events = finding.events;
+	switch (finding.type) {
+		case "bug": {
+			const error = events.find((e) => e.type === "error");
+			const fix = events.find((e) => e.type === "command_success") ?? null;
+			if (!error) return null;
+			return extractBugSolution(error, fix);
+		}
+		case "decision": {
+			const decision = events.find((e) => e.type === "user_decision");
+			if (!decision) return null;
+			return extractDecision(decision);
+		}
+		case "knowledge":
+			return extractKnowledge(events);
+		default:
+			return null;
+	}
+}
+
+function buildTitle(finding: RoutedFinding, events: typeof finding.events): string {
+	switch (finding.type) {
+		case "bug": {
+			const error = events.find((e) => e.type === "error");
+			if (!error) return "Unknown bug";
+			try {
+				const data = JSON.parse(error.data) as Record<string, unknown>;
+				const msg = typeof data.errorMessage === "string" ? data.errorMessage : "error";
+				return msg.slice(0, 80);
+			} catch {
+				return "Unknown bug";
+			}
+		}
+		case "decision": {
+			const d = events.find((e) => e.type === "user_decision");
+			if (!d) return "Decision";
+			try {
+				const data = JSON.parse(d.data) as Record<string, unknown>;
+				return typeof data.message_summary === "string" ? data.message_summary.slice(0, 80) : "Decision";
+			} catch {
+				return "Decision";
+			}
+		}
+		case "knowledge": {
+			const files = events
+				.map((e) => { try { return (JSON.parse(e.data) as Record<string, unknown>).file as string; } catch { return ""; } })
+				.filter((f) => f.length > 0);
+			return files.length > 0 ? `Pattern: ${files.join(", ")}` : "Knowledge pattern";
+		}
+		default:
+			return "Unknown finding";
+	}
+}
+
+function solutionContent(solution: Solution): string {
+	switch (solution.type) {
+		case "bug": return `${solution.problem}\n${solution.rootCause}\n${solution.fix}`;
+		case "knowledge": return `${solution.whenToUse}\n${solution.how}`;
+		case "decision": return `${solution.context}\n${solution.reasoning}`;
+	}
+}
+
+function writeSolutionToDb(db: Database.Database, title: string, solution: Solution): void {
+	const id = crypto.randomUUID();
+	const now = new Date().toISOString();
+	const content = solutionContent(solution);
+	const overlapHash = crypto.createHash("sha256").update(title + content).digest("hex");
+
+	db.prepare(`
+		INSERT INTO solutions (id, problem_type, category, title, content, files, tags, severity, overlap_hash, created_at, updated_at)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`).run(
+		id,
+		solution.type,
+		solution.type,
+		title,
+		content,
+		JSON.stringify(solution.files),
+		JSON.stringify(solution.tags),
+		"medium",
+		overlapHash,
+		now,
+		now,
+	);
+
+	// Index for search
+	indexContent(db, id, title, content, solution.type);
+}

package/src/compound/dedup.ts

@@ -0,0 +1,111 @@
+import type Database from "better-sqlite3";
+import { porterSearch } from "../store/search.ts";
+
+// ── Types ──────────────────────────────────────────────────────────────────────
+
+export interface OverlapAssessment {
+	problemOverlap: number;
+	rootCauseOverlap: number;
+	solutionOverlap: number;
+	filesOverlap: number;
+	preventionOverlap: number;
+}
+
+export interface SolutionForDedup {
+	title: string;
+	content: string;
+	files: string[];
+	tags: string[];
+}
+
+// ── Overlap assessment ─────────────────────────────────────────────────────────
+
+/**
+ * Compute text similarity between two strings using simple token overlap.
+ */
+function textSimilarity(a: string, b: string): number {
+	const tokenize = (s: string): Set<string> =>
+		new Set(s.toLowerCase().split(/\s+/).filter((t) => t.length > 2));
+	const setA = tokenize(a);
+	const setB = tokenize(b);
+	if (setA.size === 0 && setB.size === 0) return 1;
+	if (setA.size === 0 || setB.size === 0) return 0;
+	let intersection = 0;
+	for (const token of setA) {
+		if (setB.has(token)) intersection++;
+	}
+	const union = setA.size + setB.size - intersection;
+	return union > 0 ? intersection / union : 0;
+}
+
+/**
+ * Compute file set overlap (Jaccard similarity).
+ */
+function fileOverlap(filesA: string[], filesB: string[]): number {
+	if (filesA.length === 0 && filesB.length === 0) return 0;
+	if (filesA.length === 0 || filesB.length === 0) return 0;
+	const setA = new Set(filesA);
+	const setB = new Set(filesB);
+	let intersection = 0;
+	for (const f of setA) {
+		if (setB.has(f)) intersection++;
+	}
+	const union = setA.size + setB.size - intersection;
+	return union > 0 ? intersection / union : 0;
+}
+
+/**
+ * Assess overlap between a new solution and an existing solution.
+ * Uses token-based text similarity + file set intersection.
+ */
+export function assessOverlap(
+	newSol: SolutionForDedup,
+	existingSol: SolutionForDedup,
+): OverlapAssessment {
+	return {
+		problemOverlap: textSimilarity(newSol.title, existingSol.title),
+		rootCauseOverlap: textSimilarity(
+			newSol.content.slice(0, 500),
+			existingSol.content.slice(0, 500),
+		),
+		solutionOverlap: textSimilarity(newSol.content, existingSol.content),
+		filesOverlap: fileOverlap(newSol.files, existingSol.files),
+		preventionOverlap: textSimilarity(
+			newSol.tags.join(" "),
+			existingSol.tags.join(" "),
+		),
+	};
+}
+
+/**
+ * Determine if two solutions are duplicates using weighted 5-dimension check.
+ */
+export function shouldDedup(overlap: OverlapAssessment, threshold: number = 0.7): boolean {
+	const weighted =
+		overlap.problemOverlap * 0.3 +
+		overlap.rootCauseOverlap * 0.3 +
+		overlap.solutionOverlap * 0.2 +
+		overlap.filesOverlap * 0.1 +
+		overlap.preventionOverlap * 0.1;
+	return weighted > threshold;
+}
+
+/**
+ * Find potential duplicates in the database using FTS5 search.
+ */
+export function findPotentialDuplicates(
+	db: Database.Database,
+	title: string,
+): Array<{ id: string; title: string; content: string; files: string; tags: string }> {
+	try {
+		const results = porterSearch(db, title, 5);
+		const ids = results.map((r) => r.id);
+		if (ids.length === 0) return [];
+		const placeholders = ids.map(() => "?").join(",");
+		return db.prepare(
+			`SELECT id, title, content, files, tags FROM solutions WHERE id IN (${placeholders})`,
+		).all(...ids) as Array<{ id: string; title: string; content: string; files: string; tags: string }>;
+	} catch {
+		return [];
+	}
+}

package/src/compound/extractor.ts

@@ -0,0 +1,110 @@
+import type { SessionEvent } from "../store/events.ts";
+
+// ── Solution types ─────────────────────────────────────────────────────────────
+
+export interface BugSolution {
+	type: "bug";
+	problem: string;
+	rootCause: string;
+	fix: string;
+	files: string[];
+	tags: string[];
+}
+
+export interface KnowledgeSolution {
+	type: "knowledge";
+	whenToUse: string;
+	how: string;
+	tradeoffs: { pro: string[]; con: string[] };
+	files: string[];
+	tags: string[];
+}
+
+export interface DecisionSolution {
+	type: "decision";
+	context: string;
+	options: Array<{ name: string; pros: string[]; cons: string[] }>;
+	choice: string;
+	reasoning: string;
+	files: string[];
+	tags: string[];
+}
+
+export type Solution = BugSolution | KnowledgeSolution | DecisionSolution;
+
+// ── Extractors ─────────────────────────────────────────────────────────────────
+
+/**
+ * Extract a bug solution from error + fix events.
+ */
+export function extractBugSolution(
+	errorEvent: SessionEvent,
+	fixEvent: SessionEvent | null,
+): BugSolution | null {
+	let errorData: Record<string, unknown>;
+	try { errorData = JSON.parse(errorEvent.data) as Record<string, unknown>; } catch { return null; }
+
+	const errorMessage = typeof errorData.errorMessage === "string" ? errorData.errorMessage :
+		typeof errorData.message === "string" ? errorData.message : "Unknown error";
+	const tool = typeof errorData.tool === "string" ? errorData.tool : "unknown";
+
+	let fix = "No fix recorded.";
+	if (fixEvent) {
+		try {
+			const fixData = JSON.parse(fixEvent.data) as Record<string, unknown>;
+			const output = typeof fixData.output_summary === "string" ? fixData.output_summary :
+				typeof fixData.command === "string" ? `Ran: ${fixData.command}` : "";
+			if (output) fix = output;
+		} catch { /* use default */ }
+	}
+
+	return {
+		type: "bug",
+		problem: errorMessage,
+		rootCause: `Error from tool: ${tool}`,
+		fix,
+		files: [],
+		tags: [tool, "auto-extracted"],
+	};
+}
+
+/**
+ * Extract a knowledge pattern from file edit events.
+ */
+export function extractKnowledge(events: SessionEvent[]): KnowledgeSolution | null {
+	if (events.length === 0) return null;
+
+	const files = events
+		.map((e) => { try { return (JSON.parse(e.data) as Record<string, unknown>).file as string; } catch { return ""; } })
+		.filter((f) => f.length > 0);
+
+	return {
+		type: "knowledge",
+		whenToUse: `When working with: ${files.join(", ")}`,
+		how: "Pattern detected from file edit sequence.",
+		tradeoffs: { pro: [], con: [] },
+		files,
+		tags: ["auto-extracted"],
+	};
+}
+
+/**
+ * Extract a decision from user decision events.
+ */
+export function extractDecision(event: SessionEvent): DecisionSolution | null {
+	let data: Record<string, unknown>;
+	try { data = JSON.parse(event.data) as Record<string, unknown>; } catch { return null; }
+
+	const message = typeof data.message_summary === "string" ? data.message_summary :
+		typeof data.message === "string" ? data.message : "Decision made";
+
+	return {
+		type: "decision",
+		context: message,
+		options: [],
+		choice: message,
+		reasoning: "User decision captured from session.",
+		files: [],
+		tags: ["auto-extracted", "user-decision"],
+	};
+}

package/src/compound/router.ts

@@ -0,0 +1,82 @@
+import type { SessionEvent } from "../store/events.ts";
+
+export type FindingType = "bug" | "knowledge" | "decision";
+
+export interface RoutedFinding {
+	type: FindingType;
+	confidence: number;
+	events: SessionEvent[];
+}
+
+/**
+ * Route session events to the appropriate finding type.
+ * Classifies as bug/knowledge/decision based on event patterns.
+ */
+export function routeFinding(events: SessionEvent[]): RoutedFinding | null {
+	if (events.length === 0) return null;
+
+	const types = events.map((e) => e.type);
+	const hasError = types.includes("error");
+	const hasSuccess = types.includes("command_success");
+	const hasUserDecision = types.includes("user_decision");
+	const hasFileEdit = types.includes("file_edit");
+
+	// Error followed by success → bug pattern
+	if (hasError && hasSuccess && hasFileEdit) {
+		return { type: "bug", confidence: 0.8, events };
+	}
+
+	// User decision events → decision
+	if (hasUserDecision) {
+		return { type: "decision", confidence: 0.7, events };
+	}
+
+	// File edits without errors → knowledge pattern
+	if (hasFileEdit && !hasError) {
+		return { type: "knowledge", confidence: 0.5, events };
+	}
+
+	// Error without clear resolution → low-confidence bug
+	if (hasError) {
+		return { type: "bug", confidence: 0.3, events };
+	}
+
+	return null;
+}
+
+/**
+ * Route multiple sessions' events and return all routed findings.
+ */
+export function routeSessionFindings(events: SessionEvent[]): RoutedFinding[] {
+	const findings: RoutedFinding[] = [];
+
+	// Group consecutive events by context
+	const errorEvents: SessionEvent[] = [];
+	const decisionEvents: SessionEvent[] = [];
+	const editEvents: SessionEvent[] = [];
+
+	for (const event of events) {
+		if (event.type === "error" || event.type === "command_success") {
+			errorEvents.push(event);
+		} else if (event.type === "user_decision") {
+			decisionEvents.push(event);
+		} else if (event.type === "file_edit") {
+			editEvents.push(event);
+		}
+	}
+
+	if (errorEvents.length > 0) {
+		const f = routeFinding(errorEvents);
+		if (f) findings.push(f);
+	}
+
+	if (decisionEvents.length > 0) {
+		findings.push({ type: "decision", confidence: 0.7, events: decisionEvents });
+	}
+
+	if (editEvents.length > 0 && errorEvents.length === 0) {
+		findings.push({ type: "knowledge", confidence: 0.5, events: editEvents });
+	}
+
+	return findings;
+}