@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/plugin/lib/capture.ts

@@ -0,0 +1,177 @@
+/**
+ * Message Capture Module
+ *
+ * Handles message.part.updated events: extracts text content from parts,
+ * estimates tokens, and stores/updates temporal_messages for later distillation.
+ *
+ * Architecture note: OpenCode fires separate events for messages and parts.
+ * - message.updated → { info: Message } (metadata only, no text)
+ * - message.part.updated → { part: Part, delta?: string } (has text content)
+ *
+ * We capture from message.part.updated since that's where the text lives.
+ * Each part update upserts the message row, accumulating content.
+ */
+
+import {
+	type Database,
+	estimateTokens,
+	getMemoryDB,
+	MEMORY_CONFIG,
+	type TemporalMessageInput,
+} from "./memory-db.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Shape of properties from EventMessagePartUpdated */
+export interface PartEvent {
+	part?: {
+		id?: string;
+		sessionID?: string;
+		messageID?: string;
+		type?: string;
+		text?: string;
+	};
+	delta?: string;
+}
+
+/** Shape of properties from EventMessageUpdated (metadata only) */
+export interface MessageEvent {
+	info?: {
+		id?: string;
+		sessionID?: string;
+		role?: string;
+		time?: { created?: number };
+	};
+}
+
+// ============================================================================
+// Capture Handlers
+// ============================================================================
+
+/**
+ * Process a message.part.updated event.
+ * Upserts the temporal_messages row for this message, appending new text.
+ *
+ * Returns true if part was captured, false if skipped.
+ */
+export function captureMessagePart(props: PartEvent): boolean {
+	if (!MEMORY_CONFIG.capture.enabled) return false;
+
+	const part = props.part;
+	if (!part?.sessionID || !part.messageID) return false;
+
+	// Only capture text and reasoning parts
+	if (part.type !== "text" && part.type !== "reasoning") return false;
+
+	const text = part.text;
+	if (!text || text.trim().length === 0) return false;
+
+	// Cap content length
+	const cappedText = text.slice(0, MEMORY_CONFIG.capture.maxContentLength);
+
+	try {
+		const db = getMemoryDB();
+		upsertMessageContent(db, part.sessionID, part.messageID, cappedText);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Process a message.updated event to capture role metadata.
+ * Only stores role — content comes from message.part.updated.
+ *
+ * Returns true if metadata was captured.
+ */
+export function captureMessageMeta(props: MessageEvent): boolean {
+	if (!MEMORY_CONFIG.capture.enabled) return false;
+
+	const info = props.info;
+	if (!info?.id || !info.sessionID) return false;
+
+	const role = info.role ?? "unknown";
+	if (role !== "user" && role !== "assistant") return false;
+
+	try {
+		const db = getMemoryDB();
+		// Upsert with role but empty content — parts will fill it in
+		const existing = db
+			.query<{ content: string }, [string]>(
+				"SELECT content FROM temporal_messages WHERE message_id = ?",
+			)
+			.get(info.id);
+
+		if (!existing) {
+			// Insert placeholder that parts will update
+			const now = info.time?.created ?? Date.now();
+			db.run(
+				`INSERT OR IGNORE INTO temporal_messages
+				 (session_id, message_id, role, content, token_estimate, time_created)
+				 VALUES (?, ?, ?, '', 0, ?)`,
+				info.sessionID,
+				info.id,
+				role,
+				now,
+			);
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+// ============================================================================
+// Internal
+// ============================================================================
+
+/**
+ * Upsert a message row, replacing content with the latest part text.
+ * Since parts stream in incrementally, we replace (not append) with the
+ * latest full text from the part — OpenCode sends cumulative text.
+ */
+function upsertMessageContent(
+	db: Database,
+	sessionId: string,
+	messageId: string,
+	text: string,
+): void {
+	const tokenEstimate = estimateTokens(text);
+	const now = Date.now();
+
+	// Try update first (most common case — message.updated fires before parts)
+	const result = db.run(
+		`UPDATE temporal_messages
+		 SET content = ?, token_estimate = ?
+		 WHERE message_id = ?`,
+		text,
+		tokenEstimate,
+		messageId,
+	);
+
+	if (result.changes === 0) {
+		// No existing row — insert with unknown role (message.updated hasn't fired yet)
+		const input: TemporalMessageInput = {
+			session_id: sessionId,
+			message_id: messageId,
+			role: "assistant", // Parts without prior message.updated are typically assistant
+			content: text,
+			token_estimate: tokenEstimate,
+			time_created: now,
+		};
+
+		db.run(
+			`INSERT OR IGNORE INTO temporal_messages
+			 (session_id, message_id, role, content, token_estimate, time_created)
+			 VALUES (?, ?, ?, ?, ?, ?)`,
+			input.session_id,
+			input.message_id,
+			input.role,
+			input.content,
+			input.token_estimate,
+			input.time_created,
+		);
+	}
+}

package/dist/template/.opencode/plugin/lib/compact.ts

@@ -0,0 +1,194 @@
+/**
+ * Compact Format — AAAK-Inspired Memory Compression (v3)
+ *
+ * Inspired by MemPalace's AAAK dialect: a symbolic, pipe-separated format
+ * achieving ~3-5x compression while remaining readable by any LLM.
+ *
+ * Used for L1 wake-up context: compress top observations into a dense
+ * format that fits in ~200-300 tokens instead of 800+.
+ *
+ * Format rules:
+ * - Entities: 3-letter uppercase codes (ALC=Alice, KAI=Kai)
+ * - Categories: UPPERCASE labels (DECISION, PATTERN, WARNING)
+ * - Relationships: arrow notation (→, ←, ↔)
+ * - Importance: 1-5 stars (★ to ★★★★★)
+ * - Dates: ISO short (2026-03-31)
+ * - Pipe-separated fields within lines
+ */
+
+import type { CompactResult } from "./db/types.js";
+
+// ============================================================================
+// Entity Code Generation
+// ============================================================================
+
+/**
+ * Generate a 3-letter uppercase code from a name.
+ * Prioritizes: first 3 consonants, then first 3 chars.
+ */
+function generateCode(name: string): string {
+	const cleaned = name.replace(/[^a-zA-Z]/g, "").toUpperCase();
+	const consonants = cleaned.replace(/[AEIOU]/g, "");
+	if (consonants.length >= 3) return consonants.slice(0, 3);
+	return cleaned.slice(0, 3).padEnd(3, "X");
+}
+
+/**
+ * Build entity code map from observation data.
+ * Deduplicates codes by appending numbers.
+ */
+function buildCodeMap(names: string[]): Map<string, string> {
+	const codeMap = new Map<string, string>();
+	const usedCodes = new Set<string>();
+
+	for (const name of names) {
+		let code = generateCode(name);
+		if (usedCodes.has(code)) {
+			// Append incrementing suffix
+			let i = 2;
+			while (usedCodes.has(`${code.slice(0, 2)}${i}`)) i++;
+			code = `${code.slice(0, 2)}${i}`;
+		}
+		usedCodes.add(code);
+		codeMap.set(name.toLowerCase(), code);
+	}
+
+	return codeMap;
+}
+
+// ============================================================================
+// Observation Type Mapping
+// ============================================================================
+
+const TYPE_LABELS: Record<string, string> = {
+	decision: "DECISION",
+	bugfix: "FIX",
+	feature: "FEAT",
+	pattern: "PATTERN",
+	discovery: "DISC",
+	learning: "LEARN",
+	warning: "WARN",
+};
+
+const CONFIDENCE_STARS: Record<string, string> = {
+	high: "★★★",
+	medium: "★★",
+	low: "★",
+};
+
+// ============================================================================
+// Compact Compression
+// ============================================================================
+
+interface ObservationSummary {
+	id: number;
+	type: string;
+	title: string;
+	narrative?: string | null;
+	concepts?: string | null;
+	wing?: string | null;
+	hall?: string | null;
+	room?: string | null;
+	confidence?: string | null;
+	created_at?: string | null;
+}
+
+/**
+ * Compress an array of observations into compact AAAK-inspired format.
+ * Returns compressed text + compression metrics.
+ */
+export function compactObservations(
+	observations: ObservationSummary[],
+): CompactResult {
+	if (observations.length === 0) {
+		return {
+			compressed: "",
+			token_estimate: 0,
+			original_tokens: 0,
+			compression_ratio: 0,
+		};
+	}
+
+	// Estimate original size
+	const originalText = observations
+		.map(
+			(o) =>
+				`[${o.type}] ${o.title}: ${o.narrative ?? ""} (${o.concepts ?? ""})`,
+		)
+		.join("\n");
+	const originalTokens = Math.ceil(originalText.length / 4);
+
+	// Collect entities for code generation
+	const entities: string[] = [];
+	for (const obs of observations) {
+		if (obs.wing) entities.push(obs.wing);
+		if (obs.room) entities.push(obs.room);
+	}
+	const codeMap = buildCodeMap([...new Set(entities)]);
+
+	// Group by type
+	const grouped = new Map<string, ObservationSummary[]>();
+	for (const obs of observations) {
+		const key = obs.type;
+		const existing = grouped.get(key) ?? [];
+		existing.push(obs);
+		grouped.set(key, existing);
+	}
+
+	// Build compact lines
+	const lines: string[] = [];
+
+	// Header: entity legend (if entities exist)
+	if (codeMap.size > 0) {
+		const legend = [...codeMap.entries()]
+			.map(([name, code]) => `${code}=${name}`)
+			.join(" ");
+		lines.push(`ENTITIES: ${legend}`);
+	}
+
+	// Observations grouped by type
+	for (const [type, obs] of grouped) {
+		const label = TYPE_LABELS[type] ?? type.toUpperCase();
+		const entries = obs.map((o) => {
+			const parts: string[] = [];
+
+			// Title (abbreviated)
+			const shortTitle =
+				o.title.length > 60 ? `${o.title.slice(0, 57)}...` : o.title;
+			parts.push(shortTitle);
+
+			// Navigation context
+			if (o.wing || o.room) {
+				const nav: string[] = [];
+				if (o.wing) nav.push(codeMap.get(o.wing.toLowerCase()) ?? o.wing);
+				if (o.room) nav.push(codeMap.get(o.room.toLowerCase()) ?? o.room);
+				parts.push(`@${nav.join("/")}`);
+			}
+
+			// Confidence
+			if (o.confidence) {
+				parts.push(CONFIDENCE_STARS[o.confidence] ?? "★★");
+			}
+
+			// Date
+			if (o.created_at) {
+				parts.push(o.created_at.slice(0, 10));
+			}
+
+			return parts.join(" | ");
+		});
+
+		lines.push(`${label}: ${entries.join(" // ")}`);
+	}
+
+	const compressed = lines.join("\n");
+	const compressedTokens = Math.ceil(compressed.length / 4);
+
+	return {
+		compressed,
+		token_estimate: compressedTokens,
+		original_tokens: originalTokens,
+		compression_ratio:
+			originalTokens > 0 ? compressedTokens / originalTokens : 0,
+	};
+}

package/dist/template/.opencode/plugin/lib/compile.ts

@@ -0,0 +1,253 @@
+/**
+ * Memory Compilation — Observations → Structured Articles
+ *
+ * Inspired by Karpathy's LLM Wiki "compilation" layer:
+ * reads clusters of related observations and produces structured
+ * summary articles with cross-references. This is the missing 5th stage:
+ *
+ * capture → distill → curate → **compile** → inject
+ *
+ * Unlike Karpathy's approach (which uses LLM for compilation), this
+ * implementation uses pure heuristics — grouping by concept clusters,
+ * ranking by confidence/recency, and templated article generation.
+ *
+ * For LLM-powered compilation, use the compile admin operation which
+ * generates articles the agent can review and edit.
+ */
+
+import { upsertMemoryFile } from "./db/maintenance.js";
+import type { ObservationRow } from "./db/types.js";
+import { getMemoryDB } from "./memory-db.js";
+import { TYPE_ICONS, parseConcepts } from "./memory-helpers.js";
+import { appendOperationLog } from "./operation-log.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ConceptCluster {
+	concept: string;
+	observations: Pick<
+		ObservationRow,
+		"id" | "type" | "title" | "narrative" | "confidence" | "created_at"
+	>[];
+	relatedConcepts: string[];
+}
+
+export interface CompiledArticle {
+	concept: string;
+	content: string;
+	observationCount: number;
+	relatedConcepts: string[];
+}
+
+export interface CompileResult {
+	articles: CompiledArticle[];
+	totalObservations: number;
+	skippedClusters: number;
+}
+
+// ============================================================================
+// Compilation Operations
+// ============================================================================
+
+/**
+ * Compile observations into structured articles grouped by concept.
+ * Only generates articles for concepts with `minObservations` or more observations.
+ * Stores articles in memory_files as "compiled/{concept}".
+ */
+export function compileObservations(
+	options: { minObservations?: number; maxArticles?: number } = {},
+): CompileResult {
+	const minObs = options.minObservations ?? 3;
+	const maxArticles = options.maxArticles ?? 20;
+
+	const clusters = buildConceptClusters(minObs);
+	const articles: CompiledArticle[] = [];
+	let skipped = 0;
+
+	// Sort clusters by observation count (most connected first)
+	const sortedClusters = clusters
+		.sort((a, b) => b.observations.length - a.observations.length)
+		.slice(0, maxArticles);
+
+	let totalObservations = 0;
+
+	for (const cluster of sortedClusters) {
+		const article = compileCluster(cluster);
+		if (article) {
+			articles.push(article);
+			totalObservations += article.observationCount;
+			// Store in memory_files
+			const safeName = cluster.concept.replace(/[^a-z0-9-]/g, "-");
+			upsertMemoryFile(`compiled/${safeName}`, article.content, "replace");
+		} else {
+			skipped++;
+		}
+	}
+
+	// Log the operation
+	appendOperationLog({
+		operation: "compile-run",
+		targets: articles.map((a) => a.concept),
+		summary: `Compiled ${articles.length} articles from ${totalObservations} observations (${skipped} clusters skipped)`,
+	});
+
+	return { articles, totalObservations, skippedClusters: skipped };
+}
+
+// ============================================================================
+// Internal
+// ============================================================================
+
+/**
+ * Build concept clusters from active observations.
+ */
+function buildConceptClusters(minObservations: number): ConceptCluster[] {
+	const db = getMemoryDB();
+
+	const observations = db
+		.query(
+			`SELECT id, type, title, narrative, concepts, confidence, created_at
+			 FROM observations
+			 WHERE superseded_by IS NULL AND concepts IS NOT NULL
+			 ORDER BY created_at_epoch DESC`,
+		)
+		.all() as Pick<
+		ObservationRow,
+		| "id"
+		| "type"
+		| "title"
+		| "narrative"
+		| "concepts"
+		| "confidence"
+		| "created_at"
+	>[];
+
+	// Build concept → observations map
+	const conceptMap = new Map<string, typeof observations>();
+
+	for (const obs of observations) {
+		const concepts = parseConcepts(obs.concepts);
+		for (const concept of concepts) {
+			const group = conceptMap.get(concept) ?? [];
+			group.push(obs);
+			conceptMap.set(concept, group);
+		}
+	}
+
+	// Filter to clusters with enough observations
+	const clusters: ConceptCluster[] = [];
+	for (const [concept, obsGroup] of conceptMap) {
+		if (obsGroup.length < minObservations) continue;
+
+		// Find related concepts (co-occurring)
+		const relatedCounts = new Map<string, number>();
+		for (const obs of obsGroup) {
+			const concepts = parseConcepts(obs.concepts);
+			for (const c of concepts) {
+				if (c === concept) continue;
+				relatedCounts.set(c, (relatedCounts.get(c) ?? 0) + 1);
+			}
+		}
+		const relatedConcepts = [...relatedCounts.entries()]
+			.filter(([, count]) => count >= 2)
+			.sort((a, b) => b[1] - a[1])
+			.map(([c]) => c);
+
+		clusters.push({
+			concept,
+			observations: obsGroup,
+			relatedConcepts,
+		});
+	}
+
+	return clusters;
+}
+
+/**
+ * Compile a single concept cluster into a markdown article.
+ */
+function compileCluster(cluster: ConceptCluster): CompiledArticle | null {
+	if (cluster.observations.length === 0) return null;
+
+	const lines: string[] = [];
+
+	// Header
+	lines.push(`# ${cluster.concept}`);
+	lines.push("");
+	lines.push(`> Compiled from ${cluster.observations.length} observations.`);
+	lines.push(`> Last compiled: ${new Date().toISOString().slice(0, 19)}`);
+
+	// Related concepts
+	if (cluster.relatedConcepts.length > 0) {
+		lines.push(`> Related: ${cluster.relatedConcepts.join(", ")}`);
+	}
+	lines.push("");
+
+	// Group observations by type for structure
+	const byType = new Map<string, typeof cluster.observations>();
+	for (const obs of cluster.observations) {
+		const group = byType.get(obs.type) ?? [];
+		group.push(obs);
+		byType.set(obs.type, group);
+	}
+
+	// Decisions first (most important)
+	const typeOrder = [
+		"decision",
+		"pattern",
+		"warning",
+		"bugfix",
+		"discovery",
+		"feature",
+		"learning",
+	];
+	for (const type of typeOrder) {
+		const group = byType.get(type);
+		if (!group || group.length === 0) continue;
+
+		const icon = TYPE_ICONS[type] ?? "📌";
+		const heading = type.charAt(0).toUpperCase() + type.slice(1);
+		lines.push(`## ${icon} ${heading}s`);
+		lines.push("");
+
+		for (const obs of group) {
+			lines.push(`### #${obs.id}: ${obs.title}`);
+			if (obs.narrative) {
+				// Truncate long narratives for the compiled view
+				const narrative =
+					obs.narrative.length > 500
+						? `${obs.narrative.slice(0, 500)}...`
+						: obs.narrative;
+				lines.push("");
+				lines.push(narrative);
+			}
+			lines.push("");
+			lines.push(
+				`_Confidence: ${obs.confidence} | Created: ${obs.created_at.slice(0, 10)}_`,
+			);
+			lines.push("");
+		}
+	}
+
+	// Cross-reference footer
+	lines.push("---");
+	lines.push("");
+	lines.push(
+		`**Source observations:** ${cluster.observations.map((o) => `#${o.id}`).join(", ")}`,
+	);
+	if (cluster.relatedConcepts.length > 0) {
+		lines.push(
+			`**See also:** ${cluster.relatedConcepts.map((c) => `[[${c}]]`).join(", ")}`,
+		);
+	}
+
+	return {
+		concept: cluster.concept,
+		content: lines.join("\n"),
+		observationCount: cluster.observations.length,
+		relatedConcepts: cluster.relatedConcepts,
+	};
+}
+