@kodrunhq/opencode-autopilot 1.5.0 → 1.6.0

package/bin/configure-tui.ts

@@ -307,7 +307,7 @@ export async function runConfigure(configPath: string = CONFIG_PATH): Promise<vo
 
 	const newConfig = {
 		...baseConfig,
-		version: 4 as const,
+		version: 5 as const,
 		configured: true,
 		groups: groupsRecord,
 		overrides: baseConfig.overrides ?? {},

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kodrunhq/opencode-autopilot",
-	"version": "1.5.0",
+	"version": "1.6.0",
 	"description": "Curated agents, skills, and commands for the OpenCode AI coding CLI — autonomous orchestrator, multi-agent code review, model fallback, and in-session asset creation tools.",
 	"main": "src/index.ts",
 	"keywords": [

package/src/config.ts

@@ -76,6 +76,16 @@ const pluginConfigSchemaV3 = z.object({
 
 type PluginConfigV3 = z.infer<typeof pluginConfigSchemaV3>;
 
+// --- Memory sub-schema ---
+
+export const memoryConfigSchema = z.object({
+	enabled: z.boolean().default(true),
+	injectionBudget: z.number().min(500).max(5000).default(2000),
+	decayHalfLifeDays: z.number().min(7).max(365).default(90),
+});
+
+const memoryDefaults = memoryConfigSchema.parse({});
+
 // --- V4 sub-schemas ---
 
 const groupModelAssignmentSchema = z.object({
@@ -112,10 +122,37 @@ const pluginConfigSchemaV4 = z
 		}
 	});
 
-// Export aliases updated to v4
-export const pluginConfigSchema = pluginConfigSchemaV4;
+type PluginConfigV4 = z.infer<typeof pluginConfigSchemaV4>;
+
+// --- V5 schema ---
+
+const pluginConfigSchemaV5 = z
+	.object({
+		version: z.literal(5),
+		configured: z.boolean(),
+		groups: z.record(z.string(), groupModelAssignmentSchema).default({}),
+		overrides: z.record(z.string(), agentOverrideSchema).default({}),
+		orchestrator: orchestratorConfigSchema.default(orchestratorDefaults),
+		confidence: confidenceConfigSchema.default(confidenceDefaults),
+		fallback: fallbackConfigSchema.default(fallbackDefaults),
+		memory: memoryConfigSchema.default(memoryDefaults),
+	})
+	.superRefine((config, ctx) => {
+		for (const groupId of Object.keys(config.groups)) {
+			if (!ALL_GROUP_IDS.includes(groupId as (typeof ALL_GROUP_IDS)[number])) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					path: ["groups", groupId],
+					message: `Unknown group id "${groupId}". Expected one of: ${ALL_GROUP_IDS.join(", ")}`,
+				});
+			}
+		}
+	});
+
+// Export aliases updated to v5
+export const pluginConfigSchema = pluginConfigSchemaV5;
 
-export type PluginConfig = z.infer<typeof pluginConfigSchemaV4>;
+export type PluginConfig = z.infer<typeof pluginConfigSchemaV5>;
 
 export const CONFIG_PATH = join(getGlobalConfigDir(), "opencode-autopilot.json");
 
@@ -142,7 +179,7 @@ function migrateV2toV3(v2Config: PluginConfigV2): PluginConfigV3 {
 	};
 }
 
-function migrateV3toV4(v3Config: PluginConfigV3): PluginConfig {
+function migrateV3toV4(v3Config: PluginConfigV3): PluginConfigV4 {
 	const groups: Record<string, { primary: string; fallbacks: string[] }> = {};
 	const overrides: Record<string, { primary: string }> = {};
 
@@ -191,6 +228,19 @@ function migrateV3toV4(v3Config: PluginConfigV3): PluginConfig {
 	};
 }
 
+function migrateV4toV5(v4Config: PluginConfigV4): PluginConfig {
+	return {
+		version: 5 as const,
+		configured: v4Config.configured,
+		groups: v4Config.groups,
+		overrides: v4Config.overrides,
+		orchestrator: v4Config.orchestrator,
+		confidence: v4Config.confidence,
+		fallback: v4Config.fallback,
+		memory: memoryDefaults,
+	};
+}
+
 // --- Public API ---
 
 export async function loadConfig(configPath: string = CONFIG_PATH): Promise<PluginConfig | null> {
@@ -198,38 +248,49 @@ export async function loadConfig(configPath: string = CONFIG_PATH): Promise<Plug
 		const raw = await readFile(configPath, "utf-8");
 		const parsed = JSON.parse(raw);
 
-		// Try v4 first
+		// Try v5 first
+		const v5Result = pluginConfigSchemaV5.safeParse(parsed);
+		if (v5Result.success) return v5Result.data;
+
+		// Try v4 and migrate to v5
 		const v4Result = pluginConfigSchemaV4.safeParse(parsed);
-		if (v4Result.success) return v4Result.data;
+		if (v4Result.success) {
+			const migrated = migrateV4toV5(v4Result.data);
+			await saveConfig(migrated, configPath);
+			return migrated;
+		}
 
-		// Try v3 and migrate to v4
+		// Try v3 → v4 → v5
 		const v3Result = pluginConfigSchemaV3.safeParse(parsed);
 		if (v3Result.success) {
-			const migrated = migrateV3toV4(v3Result.data);
+			const v4 = migrateV3toV4(v3Result.data);
+			const migrated = migrateV4toV5(v4);
 			await saveConfig(migrated, configPath);
 			return migrated;
 		}
 
-		// Try v2 → v3 → v4
+		// Try v2 → v3 → v4 → v5
 		const v2Result = pluginConfigSchemaV2.safeParse(parsed);
 		if (v2Result.success) {
 			const v3 = migrateV2toV3(v2Result.data);
-			const migrated = migrateV3toV4(v3);
+			const v4 = migrateV3toV4(v3);
+			const migrated = migrateV4toV5(v4);
 			await saveConfig(migrated, configPath);
 			return migrated;
 		}
 
-		// Try v1 → v2 → v3 → v4
+		// Try v1 → v2 → v3 → v4 → v5
 		const v1Result = pluginConfigSchemaV1.safeParse(parsed);
 		if (v1Result.success) {
 			const v2 = migrateV1toV2(v1Result.data);
 			const v3 = migrateV2toV3(v2);
-			const migrated = migrateV3toV4(v3);
+			const v4 = migrateV3toV4(v3);
+			const migrated = migrateV4toV5(v4);
 			await saveConfig(migrated, configPath);
 			return migrated;
 		}
 
-		return pluginConfigSchemaV4.parse(parsed); // throw with proper error
+		return pluginConfigSchemaV5.parse(parsed); // throw with proper error
 	} catch (error: unknown) {
 		if (isEnoentError(error)) return null;
 		throw error;
@@ -252,12 +313,13 @@ export function isFirstLoad(config: PluginConfig | null): boolean {
 
 export function createDefaultConfig(): PluginConfig {
 	return {
-		version: 4 as const,
+		version: 5 as const,
 		configured: false,
 		groups: {},
 		overrides: {},
 		orchestrator: orchestratorDefaults,
 		confidence: confidenceDefaults,
 		fallback: fallbackDefaults,
+		memory: memoryDefaults,
 	};
 }

package/src/index.ts

@@ -3,6 +3,7 @@ import { configHook } from "./agents";
 import { isFirstLoad, loadConfig } from "./config";
 import { runHealthChecks } from "./health/runner";
 import { installAssets } from "./installer";
+import { createMemoryCaptureHandler, createMemoryInjector, getMemoryDb } from "./memory";
 import { ContextMonitor } from "./observability/context-monitor";
 import {
 	createObservabilityEventHandler,
@@ -35,6 +36,7 @@ import { ocCreateSkill } from "./tools/create-skill";
 import { ocDoctor } from "./tools/doctor";
 import { ocForensics } from "./tools/forensics";
 import { ocLogs } from "./tools/logs";
+import { ocMemoryStatus } from "./tools/memory-status";
 import { ocMockFallback } from "./tools/mock-fallback";
 import { ocOrchestrate } from "./tools/orchestrate";
 import { ocPhase } from "./tools/phase";
@@ -148,6 +150,26 @@ const plugin: Plugin = async (input) => {
 	const chatMessageHandler = createChatMessageHandler(manager);
 	const toolExecuteAfterHandler = createToolExecuteAfterHandler(manager);
 
+	// --- Memory subsystem initialization ---
+	const memoryConfig = config?.memory ?? {
+		enabled: true,
+		injectionBudget: 2000,
+		decayHalfLifeDays: 90,
+	};
+
+	const memoryCaptureHandler = memoryConfig.enabled
+		? createMemoryCaptureHandler({ getDb: () => getMemoryDb(), projectRoot: process.cwd() })
+		: null;
+
+	const memoryInjector = memoryConfig.enabled
+		? createMemoryInjector({
+				projectRoot: process.cwd(),
+				tokenBudget: memoryConfig.injectionBudget,
+				halfLifeDays: memoryConfig.decayHalfLifeDays,
+				getDb: () => getMemoryDb(),
+			})
+		: null;
+
 	// --- Observability handlers ---
 	const toolStartTimes = new Map<string, number>();
 	const observabilityEventHandler = createObservabilityEventHandler({
@@ -195,12 +217,22 @@ const plugin: Plugin = async (input) => {
 			oc_mock_fallback: ocMockFallback,
 			oc_stocktake: ocStocktake,
 			oc_update_docs: ocUpdateDocs,
+			oc_memory_status: ocMemoryStatus,
 		},
 		event: async ({ event }) => {
 			// 1. Observability: collect (pure observer, no side effects on session)
 			await observabilityEventHandler({ event });
 
-			// 2. First-load toast
+			// 2. Memory capture (pure observer, best-effort)
+			if (memoryCaptureHandler) {
+				try {
+					await memoryCaptureHandler({ event });
+				} catch {
+					/* best-effort */
+				}
+			}
+
+			// 3. First-load toast
 			if (event.type === "session.created" && isFirstLoad(config)) {
 				await sdkOps.showToast(
 					"Welcome to OpenCode Autopilot!",
@@ -209,7 +241,7 @@ const plugin: Plugin = async (input) => {
 				);
 			}
 
-			// 3. Fallback event handling
+			// 4. Fallback event handling
 			if (fallbackConfig.enabled) {
 				await fallbackEventHandler({ event });
 			}
@@ -257,6 +289,11 @@ const plugin: Plugin = async (input) => {
 				await toolExecuteAfterHandler(hookInput, output);
 			}
 		},
+		"experimental.chat.system.transform": async (input, output) => {
+			if (memoryInjector) {
+				await memoryInjector(input, output);
+			}
+		},
 	};
 };
 

package/src/memory/capture.ts

@@ -0,0 +1,205 @@
+/**
+ * Event capture handler for memory observations.
+ *
+ * Subscribes to OpenCode session events and extracts memory-worthy
+ * observations from decision, error, and phase_transition events.
+ * Noisy events (tool_complete, context_warning, session_start/end)
+ * are filtered out per Research Pitfall 4.
+ *
+ * Factory pattern matches createObservabilityEventHandler in
+ * src/observability/event-handlers.ts.
+ *
+ * @module
+ */
+
+import type { Database } from "bun:sqlite";
+import { basename } from "node:path";
+import { pruneStaleObservations } from "./decay";
+import { computeProjectKey } from "./project-key";
+import { insertObservation, upsertProject } from "./repository";
+import type { ObservationType } from "./types";
+
+/**
+ * Dependencies for the memory capture handler.
+ */
+export interface MemoryCaptureDeps {
+	readonly getDb: () => Database;
+	readonly projectRoot: string;
+}
+
+/**
+ * Events that produce memory observations.
+ */
+const CAPTURE_EVENT_TYPES = new Set([
+	"session.created",
+	"session.deleted",
+	"session.error",
+	"app.decision",
+	"app.phase_transition",
+]);
+
+/**
+ * Extracts a session ID from event properties.
+ * Supports properties.sessionID, properties.info.id, properties.info.sessionID.
+ */
+function extractSessionId(properties: Record<string, unknown>): string | undefined {
+	if (typeof properties.sessionID === "string") return properties.sessionID;
+	if (properties.info !== null && typeof properties.info === "object") {
+		const info = properties.info as Record<string, unknown>;
+		if (typeof info.sessionID === "string") return info.sessionID;
+		if (typeof info.id === "string") return info.id;
+	}
+	return undefined;
+}
+
+/**
+ * Safely truncate a string to maxLen characters.
+ */
+function truncate(s: string, maxLen: number): string {
+	return s.length > maxLen ? s.slice(0, maxLen) : s;
+}
+
+/**
+ * Creates a memory capture handler that subscribes to OpenCode events.
+ *
+ * Returns an async function matching the event handler signature:
+ * `(input: { event: { type: string; [key: string]: unknown } }) => Promise<void>`
+ *
+ * Pure observer: never modifies the event or session output.
+ */
+export function createMemoryCaptureHandler(deps: MemoryCaptureDeps) {
+	let currentSessionId: string | null = null;
+	let currentProjectKey: string | null = null;
+
+	const now = () => new Date().toISOString();
+
+	function safeInsert(
+		type: ObservationType,
+		content: string,
+		summary: string,
+		confidence: number,
+	): void {
+		if (!currentSessionId || !currentProjectKey) return;
+		try {
+			insertObservation(
+				{
+					projectId: currentProjectKey,
+					sessionId: currentSessionId,
+					type,
+					content,
+					summary: truncate(summary, 200),
+					confidence,
+					accessCount: 0,
+					createdAt: now(),
+					lastAccessed: now(),
+				},
+				deps.getDb(),
+			);
+		} catch (err) {
+			console.warn("[opencode-autopilot] memory capture failed:", err);
+		}
+	}
+
+	return async (input: {
+		readonly event: { readonly type: string; readonly [key: string]: unknown };
+	}): Promise<void> => {
+		const { event } = input;
+		const properties = (event.properties ?? {}) as Record<string, unknown>;
+
+		// Skip noisy events early
+		if (!CAPTURE_EVENT_TYPES.has(event.type)) return;
+
+		switch (event.type) {
+			case "session.created": {
+				const rawInfo = properties.info;
+				if (rawInfo === null || typeof rawInfo !== "object") return;
+				const info = rawInfo as { id?: string };
+				if (!info.id) return;
+
+				currentSessionId = info.id;
+				currentProjectKey = computeProjectKey(deps.projectRoot);
+				const projectName = basename(deps.projectRoot);
+
+				try {
+					upsertProject(
+						{
+							id: currentProjectKey,
+							path: deps.projectRoot,
+							name: projectName,
+							lastUpdated: now(),
+						},
+						deps.getDb(),
+					);
+				} catch (err) {
+					console.warn("[opencode-autopilot] upsertProject failed:", err);
+				}
+				return;
+			}
+
+			case "session.deleted": {
+				const projectKey = currentProjectKey;
+				const db = deps.getDb();
+
+				// Reset state
+				currentSessionId = null;
+				currentProjectKey = null;
+
+				// Defer pruning to avoid blocking the event loop
+				if (projectKey) {
+					setTimeout(() => {
+						try {
+							pruneStaleObservations(projectKey, db);
+						} catch (err) {
+							console.warn("[opencode-autopilot] pruneStaleObservations failed:", err);
+						}
+					}, 0);
+				}
+				return;
+			}
+
+			case "session.error": {
+				const sessionId = extractSessionId(properties);
+				if (!sessionId || sessionId !== currentSessionId) return;
+
+				const error = properties.error as Record<string, unknown> | undefined;
+				const errorType = typeof error?.type === "string" ? error.type : "unknown";
+				const message = typeof error?.message === "string" ? error.message : "Unknown error";
+				const content = `${errorType}: ${message}`;
+				const summary = truncate(message, 200);
+
+				safeInsert("error", content, summary, 0.7);
+				return;
+			}
+
+			case "app.decision": {
+				const sessionId = extractSessionId(properties);
+				if (!sessionId || sessionId !== currentSessionId) return;
+
+				const decision = typeof properties.decision === "string" ? properties.decision : "";
+				const rationale = typeof properties.rationale === "string" ? properties.rationale : "";
+
+				if (!decision) return;
+
+				safeInsert("decision", decision, rationale || truncate(decision, 200), 0.8);
+				return;
+			}
+
+			case "app.phase_transition": {
+				const sessionId = extractSessionId(properties);
+				if (!sessionId || sessionId !== currentSessionId) return;
+
+				const fromPhase =
+					typeof properties.fromPhase === "string" ? properties.fromPhase : "unknown";
+				const toPhase = typeof properties.toPhase === "string" ? properties.toPhase : "unknown";
+				const content = `Phase transition: ${fromPhase} -> ${toPhase}`;
+				const summary = content;
+
+				safeInsert("pattern", content, summary, 0.6);
+				return;
+			}
+
+			default:
+				return;
+		}
+	};
+}

package/src/memory/constants.ts

@@ -0,0 +1,26 @@
+export const OBSERVATION_TYPES = [
+	"decision",
+	"pattern",
+	"error",
+	"preference",
+	"context",
+	"tool_usage",
+] as const;
+
+export const TYPE_WEIGHTS: Readonly<Record<(typeof OBSERVATION_TYPES)[number], number>> =
+	Object.freeze({
+		decision: 1.5,
+		pattern: 1.2,
+		error: 1.0,
+		preference: 0.8,
+		context: 0.6,
+		tool_usage: 0.4,
+	});
+
+export const DEFAULT_INJECTION_BUDGET = 2000;
+export const DEFAULT_HALF_LIFE_DAYS = 90;
+export const CHARS_PER_TOKEN = 4;
+export const MAX_OBSERVATIONS_PER_PROJECT = 10000;
+export const MIN_RELEVANCE_THRESHOLD = 0.1;
+export const MEMORY_DIR = "memory";
+export const DB_FILE = "memory.db";

package/src/memory/database.ts

@@ -0,0 +1,103 @@
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { getGlobalConfigDir } from "../utils/paths";
+import { DB_FILE, MEMORY_DIR } from "./constants";
+
+let db: Database | null = null;
+
+/**
+ * Run all CREATE TABLE / CREATE INDEX / CREATE TRIGGER migrations.
+ * Idempotent via IF NOT EXISTS.
+ */
+export function initMemoryDb(database: Database): void {
+	database.run(`CREATE TABLE IF NOT EXISTS projects (
+		id TEXT PRIMARY KEY,
+		path TEXT NOT NULL UNIQUE,
+		name TEXT NOT NULL,
+		last_updated TEXT NOT NULL
+	)`);
+
+	database.run(`CREATE TABLE IF NOT EXISTS observations (
+		id INTEGER PRIMARY KEY,
+		project_id TEXT,
+		session_id TEXT NOT NULL,
+		type TEXT NOT NULL CHECK(type IN ('decision','pattern','error','preference','context','tool_usage')),
+		content TEXT NOT NULL,
+		summary TEXT NOT NULL,
+		confidence REAL NOT NULL DEFAULT 0.5,
+		access_count INTEGER NOT NULL DEFAULT 0,
+		created_at TEXT NOT NULL,
+		last_accessed TEXT NOT NULL,
+		FOREIGN KEY (project_id) REFERENCES projects(id)
+	)`);
+
+	database.run(`CREATE TABLE IF NOT EXISTS preferences (
+		id TEXT PRIMARY KEY,
+		key TEXT NOT NULL UNIQUE,
+		value TEXT NOT NULL,
+		confidence REAL NOT NULL DEFAULT 0.5,
+		source_session TEXT,
+		created_at TEXT NOT NULL,
+		last_updated TEXT NOT NULL
+	)`);
+
+	database.run(`CREATE VIRTUAL TABLE IF NOT EXISTS observations_fts USING fts5(
+		content, summary,
+		content=observations,
+		content_rowid=id
+	)`);
+
+	database.run(`CREATE TRIGGER IF NOT EXISTS obs_ai AFTER INSERT ON observations BEGIN
+		INSERT INTO observations_fts(rowid, content, summary)
+		VALUES (new.id, new.content, new.summary);
+	END`);
+
+	database.run(`CREATE TRIGGER IF NOT EXISTS obs_ad AFTER DELETE ON observations BEGIN
+		INSERT INTO observations_fts(observations_fts, rowid, content, summary)
+		VALUES('delete', old.id, old.content, old.summary);
+	END`);
+
+	database.run(`CREATE TRIGGER IF NOT EXISTS obs_au AFTER UPDATE ON observations BEGIN
+		INSERT INTO observations_fts(observations_fts, rowid, content, summary)
+		VALUES('delete', old.id, old.content, old.summary);
+		INSERT INTO observations_fts(rowid, content, summary)
+		VALUES (new.id, new.content, new.summary);
+	END`);
+
+	database.run(`CREATE INDEX IF NOT EXISTS idx_observations_project ON observations(project_id)`);
+	database.run(`CREATE INDEX IF NOT EXISTS idx_observations_type ON observations(type)`);
+}
+
+/**
+ * Get or create the singleton memory database.
+ * Accepts optional dbPath for testing (e.g. ":memory:").
+ */
+export function getMemoryDb(dbPath?: string): Database {
+	if (db) return db;
+
+	const resolvedPath =
+		dbPath ??
+		(() => {
+			const memoryDir = join(getGlobalConfigDir(), MEMORY_DIR);
+			mkdirSync(memoryDir, { recursive: true });
+			return join(memoryDir, DB_FILE);
+		})();
+
+	db = new Database(resolvedPath);
+	db.run("PRAGMA journal_mode=WAL");
+	db.run("PRAGMA foreign_keys=ON");
+	db.run("PRAGMA busy_timeout=5000");
+	initMemoryDb(db);
+	return db;
+}
+
+/**
+ * Close the singleton database and reset.
+ */
+export function closeMemoryDb(): void {
+	if (db) {
+		db.close();
+		db = null;
+	}
+}

package/src/memory/decay.ts

@@ -0,0 +1,94 @@
+/**
+ * Time-weighted decay computation and pruning for memory observations.
+ *
+ * Relevance score = timeDecay * frequencyWeight * typeWeight
+ * - timeDecay: exponential decay with configurable half-life (default 90 days)
+ * - frequencyWeight: log2(accessCount + 1), minimum 1
+ * - typeWeight: per-type multiplier from constants
+ *
+ * @module
+ */
+
+import type { Database } from "bun:sqlite";
+import {
+	DEFAULT_HALF_LIFE_DAYS,
+	MAX_OBSERVATIONS_PER_PROJECT,
+	MIN_RELEVANCE_THRESHOLD,
+	TYPE_WEIGHTS,
+} from "./constants";
+import { deleteObservation, getObservationsByProject } from "./repository";
+import type { ObservationType } from "./types";
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/**
+ * Compute the relevance score for an observation.
+ *
+ * Formula: timeDecay * frequencyWeight * typeWeight
+ * - timeDecay = exp(-ageDays / halfLifeDays)
+ * - frequencyWeight = max(log2(accessCount + 1), 1)
+ * - typeWeight = TYPE_WEIGHTS[type]
+ */
+export function computeRelevanceScore(
+	lastAccessed: string,
+	accessCount: number,
+	type: ObservationType,
+	halfLifeDays: number = DEFAULT_HALF_LIFE_DAYS,
+): number {
+	const ageMs = Date.now() - new Date(lastAccessed).getTime();
+	const ageDays = ageMs / MS_PER_DAY;
+	const timeDecay = Math.exp(-ageDays / halfLifeDays);
+	const frequencyWeight = Math.max(Math.log2(accessCount + 1), 1);
+	const typeWeight = TYPE_WEIGHTS[type];
+	return timeDecay * frequencyWeight * typeWeight;
+}
+
+/**
+ * Prune stale observations for a project.
+ *
+ * 1. Remove observations where relevance score < MIN_RELEVANCE_THRESHOLD
+ * 2. If remaining count > MAX_OBSERVATIONS_PER_PROJECT, remove lowest-scored until at cap
+ *
+ * Uses deleteObservation for each deletion (not batch DELETE for safety).
+ */
+export function pruneStaleObservations(
+	projectId: string | null,
+	db?: Database,
+): { readonly pruned: number } {
+	const fetchLimit = MAX_OBSERVATIONS_PER_PROJECT + 1000;
+	const observations = getObservationsByProject(projectId, fetchLimit, db);
+
+	// Score each observation — skip any without a valid id (schema allows optional)
+	const scored = observations
+		.filter((obs): obs is typeof obs & { id: number } => obs.id !== undefined)
+		.map((obs) => ({
+			id: obs.id,
+			score: computeRelevanceScore(obs.lastAccessed, obs.accessCount, obs.type),
+		}));
+
+	let pruned = 0;
+
+	// Phase 1: Remove observations below threshold
+	const belowThreshold = scored.filter((s) => s.score < MIN_RELEVANCE_THRESHOLD);
+	for (const entry of belowThreshold) {
+		deleteObservation(entry.id, db);
+		pruned++;
+	}
+
+	// Phase 2: Enforce cap on remaining
+	const remaining = scored
+		.filter((s) => s.score >= MIN_RELEVANCE_THRESHOLD)
+		.sort((a, b) => a.score - b.score);
+
+	const excess = remaining.length - MAX_OBSERVATIONS_PER_PROJECT;
+	if (excess > 0) {
+		// Remove lowest-scored excess
+		const toRemove = remaining.slice(0, excess);
+		for (const entry of toRemove) {
+			deleteObservation(entry.id, db);
+			pruned++;
+		}
+	}
+
+	return Object.freeze({ pruned });
+}