@ultrakit/ultrakit 0.0.0

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

@@ -0,0 +1,198 @@
+/**
+ * Context Window Management Module
+ *
+ * Implements messages.transform: estimates token usage across conversation
+ * messages and compresses oldest messages when approaching the budget limit.
+ *
+ * Protects the most recent N messages from compression.
+ */
+
+import { estimateTokens, MEMORY_CONFIG } from "./memory-db.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Minimal message shape from messages.transform output */
+interface TransformMessage {
+	info: {
+		id?: string;
+		role?: string;
+		time?: {
+			created?: number;
+		};
+	};
+	parts: Array<{
+		type?: string;
+		text?: string;
+		data?: {
+			type?: string;
+			text?: string;
+		};
+	}>;
+}
+
+// ============================================================================
+// Token Estimation
+// ============================================================================
+
+/**
+ * Estimate total tokens in a message (all text parts).
+ */
+function estimateMessageTokens(msg: TransformMessage): number {
+	let total = 0;
+	for (const part of msg.parts) {
+		if (part.text) {
+			total += estimateTokens(part.text);
+		} else if (part.data?.text) {
+			total += estimateTokens(part.data.text);
+		}
+	}
+	// Add overhead for message framing (~10 tokens per message)
+	return total + 10;
+}
+
+/**
+ * Create a compressed summary of a message.
+ * Preserves non-text parts (tool calls, tool results, images) to maintain
+ * conversation coherence. Only compresses text parts.
+ */
+function compressMessage(msg: TransformMessage): TransformMessage {
+	const role = msg.info.role ?? "unknown";
+
+	// Separate text parts from non-text parts (tool calls, tool results, etc.)
+	const textParts: Array<(typeof msg.parts)[number]> = [];
+	const nonTextParts: Array<(typeof msg.parts)[number]> = [];
+
+	for (const part of msg.parts) {
+		const isTextPart =
+			part.type === "text" || (!part.type && (part.text || part.data?.text));
+		if (isTextPart) {
+			textParts.push(part);
+		} else {
+			nonTextParts.push(part);
+		}
+	}
+
+	// Extract text content for summarization
+	const texts: string[] = [];
+	for (const part of textParts) {
+		if (part.text) texts.push(part.text);
+		else if (part.data?.text) texts.push(part.data.text);
+	}
+
+	const fullText = texts.join("\n");
+
+	// Build compressed parts: summarized text + preserved non-text parts
+	const compressedParts: typeof msg.parts = [];
+
+	if (fullText.length > 0) {
+		compressedParts.push({
+			type: "text",
+			text: createSummary(fullText, role),
+		});
+	}
+
+	// Preserve tool calls, tool results, and other structural parts
+	compressedParts.push(...nonTextParts);
+
+	return {
+		info: msg.info,
+		parts:
+			compressedParts.length > 0
+				? compressedParts
+				: [{ type: "text", text: `[compressed ${role} message]` }],
+	};
+}
+
+/**
+ * Create a brief summary of message content.
+ * Keeps first and last sentence, truncates middle.
+ */
+function createSummary(text: string, role: string): string {
+	const maxChars = 500;
+
+	if (text.length <= maxChars) return text;
+
+	// For very large messages (>5000 chars), be more aggressive
+	const isLarge = text.length > 5000;
+	const effectiveMax = isLarge ? 300 : maxChars;
+
+	// Split into sentences
+	const sentences = text
+		.split(/(?<=[.!?])\s+|\n+/)
+		.map((s) => s.trim())
+		.filter((s) => s.length > 0);
+
+	if (sentences.length <= 2) {
+		return `${text.slice(0, effectiveMax)}...`;
+	}
+
+	const first = sentences[0];
+	const last = sentences[sentences.length - 1];
+
+	const summary = `[compressed ${role}] ${first} [...${sentences.length - 2} sentences...] ${last}`;
+
+	return summary.length > effectiveMax
+		? `${summary.slice(0, effectiveMax)}...`
+		: summary;
+}
+
+// ============================================================================
+// Context Manager
+// ============================================================================
+
+/**
+ * Process messages through context management.
+ *
+ * If total tokens exceed maxContextTokens, compresses oldest messages
+ * (excluding the most recent `protectedMessages` count).
+ *
+ * @param messages - Current conversation messages
+ * @returns Potentially compressed messages array
+ */
+export function manageContext(
+	messages: TransformMessage[],
+): TransformMessage[] {
+	if (!MEMORY_CONFIG.context.enabled) return messages;
+
+	const maxTokens = MEMORY_CONFIG.context.maxContextTokens;
+	const protectedCount = MEMORY_CONFIG.context.protectedMessages;
+
+	// Estimate total tokens
+	let totalTokens = 0;
+	const tokenCounts: number[] = [];
+
+	for (const msg of messages) {
+		const tokens = estimateMessageTokens(msg);
+		tokenCounts.push(tokens);
+		totalTokens += tokens;
+	}
+
+	// If under budget, return unchanged
+	if (totalTokens <= maxTokens) return messages;
+
+	// Calculate how many tokens to shed
+	const tokensToShed = totalTokens - maxTokens;
+
+	// Identify compressible messages (all except protected recent ones)
+	const compressibleEnd = Math.max(0, messages.length - protectedCount);
+	let shedSoFar = 0;
+
+	const result = [...messages];
+
+	// Compress from oldest to newest until we've shed enough
+	for (let i = 0; i < compressibleEnd && shedSoFar < tokensToShed; i++) {
+		const originalTokens = tokenCounts[i];
+		const compressed = compressMessage(messages[i]);
+		const compressedTokens = estimateMessageTokens(compressed);
+		const saved = originalTokens - compressedTokens;
+
+		if (saved > 0) {
+			result[i] = compressed;
+			shedSoFar += saved;
+		}
+	}
+
+	return result;
+}

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

@@ -0,0 +1,234 @@
+/**
+ * Curator Module
+ *
+ * Pattern-matches distillations to automatically create observations.
+ * Uses regex patterns to detect decisions, bugfixes, patterns, discoveries, warnings.
+ * All curated observations are created with source='curator'.
+ *
+ * No LLM dependency — pure heuristic pattern matching.
+ */
+
+import {
+	type DistillationRow,
+	getRecentDistillations,
+	MEMORY_CONFIG,
+	type ObservationInput,
+	type ObservationType,
+	storeObservation,
+} from "./memory-db.js";
+
+// ============================================================================
+// Pattern Definitions
+// ============================================================================
+
+/** Curator patterns — regex + type mapping.
+ *
+ * Each pattern requires multi-word phrases or contextual markers to reduce
+ * false positives. Single common words like "using", "found", "always" are
+ * NOT matched alone — they must appear in decision/discovery phrases.
+ */
+const CURATOR_PATTERNS: Array<{
+	type: ObservationType;
+	pattern: RegExp;
+	titleExtractor: (match: RegExpMatchArray, sentence: string) => string;
+}> = [
+	{
+		type: "decision",
+		pattern:
+			/\b(decided to|chose to|selected\s+\w+\s+(?:over|instead)|went with|opted for|switched to|migrated to|picked\s+\w+\s+(?:over|for))\b/i,
+		titleExtractor: (_match, sentence) => truncateSentence(sentence, 80),
+	},
+	{
+		type: "bugfix",
+		pattern:
+			/\b(fixed (?:a|the|an)\b|resolved (?:a|the|an)\b|patched (?:a|the|an)\b|corrected (?:a|the|an)\b|bug in\b|error in\b|crash in\b|regression in\b)\b/i,
+		titleExtractor: (_match, sentence) => truncateSentence(sentence, 80),
+	},
+	{
+		type: "pattern",
+		pattern:
+			/\b(pattern(?::|is| for)\b|convention(?::|is)\b|best practice\b|standard practice\b|workflow for\b|(?:we|I|the team) (?:always|never)\b)\b/i,
+		titleExtractor: (_match, sentence) => truncateSentence(sentence, 80),
+	},
+	{
+		type: "discovery",
+		pattern:
+			/\b(found that|discovered that|noticed that|learned that|turns out|realized that|it (?:seems|appears) that)\b/i,
+		titleExtractor: (_match, sentence) => truncateSentence(sentence, 80),
+	},
+	{
+		type: "warning",
+		pattern:
+			/\b(warning:|caution:|careful with|gotcha:|pitfall(?:s|:)?\b|don't use\b|avoid (?:using|calling|importing)\b|beware of\b|watch out for\b|never (?:use|call|import|commit|push)\b)\b/i,
+		titleExtractor: (_match, sentence) => truncateSentence(sentence, 80),
+	},
+];
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+/**
+ * Truncate a sentence to max length, preserving word boundaries.
+ */
+function truncateSentence(sentence: string, maxLen: number): string {
+	const clean = sentence.replace(/\s+/g, " ").trim();
+	if (clean.length <= maxLen) return clean;
+
+	const truncated = clean.slice(0, maxLen);
+	const lastSpace = truncated.lastIndexOf(" ");
+	return lastSpace > maxLen / 2
+		? `${truncated.slice(0, lastSpace)}...`
+		: `${truncated}...`;
+}
+
+/**
+ * Split distillation content into sentences.
+ */
+function splitSentences(content: string): string[] {
+	return content
+		.split(/(?<=[.!?])\s+|\n+/)
+		.map((s) => s.trim())
+		.filter((s) => s.length > 30); // Skip short fragments that lack enough context
+}
+
+/**
+ * Extract concept tags from a sentence (significant nouns/terms).
+ */
+function extractConcepts(sentence: string): string[] {
+	// Extract potential concept words (3+ chars, not common stop words)
+	const words = sentence
+		.toLowerCase()
+		.replace(/[^a-z0-9_\-/.]+/g, " ")
+		.split(/\s+/)
+		.filter((w) => w.length > 3);
+
+	// Return unique terms, limited to 5
+	return [...new Set(words)].slice(0, 5);
+}
+
+/**
+ * Deduplicate against existing observation titles (simple guard).
+ * Returns true if a similar title already exists.
+ */
+function isDuplicateTitle(title: string, existingTitles: Set<string>): boolean {
+	const normalized = title.toLowerCase().trim();
+	if (existingTitles.has(normalized)) return true;
+
+	// Also check prefix match (first 40 chars) for fuzzy dedup
+	const prefix = normalized.slice(0, 40);
+	for (const existing of existingTitles) {
+		if (
+			existing.startsWith(prefix) ||
+			prefix.startsWith(existing.slice(0, 40))
+		) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+// ============================================================================
+// Curator Pipeline
+// ============================================================================
+
+interface CuratorResult {
+	created: number;
+	skipped: number;
+	patterns: Record<string, number>;
+}
+
+/**
+ * Run curator on recent distillations to extract observations.
+ *
+ * @param sessionId - If provided, only process distillations from this session
+ * @param limit - Max distillations to process (default: MEMORY_CONFIG.curator.minDistillations)
+ */
+export function curateFromDistillations(
+	sessionId?: string,
+	limit?: number,
+): CuratorResult {
+	if (!MEMORY_CONFIG.curator.enabled) {
+		return { created: 0, skipped: 0, patterns: {} };
+	}
+
+	const maxDistillations = limit ?? MEMORY_CONFIG.curator.minDistillations;
+	const distillations = getRecentDistillations(sessionId, maxDistillations);
+
+	if (distillations.length < MEMORY_CONFIG.curator.minDistillations) {
+		return { created: 0, skipped: 0, patterns: {} };
+	}
+
+	const result: CuratorResult = { created: 0, skipped: 0, patterns: {} };
+	const seenTitles = new Set<string>();
+
+	for (const distillation of distillations) {
+		const sentences = splitSentences(distillation.content);
+
+		for (const sentence of sentences) {
+			const observation = matchPatterns(sentence, distillation, seenTitles);
+
+			if (observation) {
+				try {
+					storeObservation(observation);
+					result.created++;
+					result.patterns[observation.type] =
+						(result.patterns[observation.type] ?? 0) + 1;
+					seenTitles.add(observation.title.toLowerCase().trim());
+				} catch {
+					result.skipped++;
+				}
+			}
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Match a sentence against curator patterns and return an observation input if matched.
+ */
+function matchPatterns(
+	sentence: string,
+	distillation: DistillationRow,
+	seenTitles: Set<string>,
+): ObservationInput | null {
+	for (const { type, pattern, titleExtractor } of CURATOR_PATTERNS) {
+		const match = sentence.match(pattern);
+		if (!match) continue;
+
+		const title = titleExtractor(match, sentence);
+
+		// Skip duplicates
+		if (isDuplicateTitle(title, seenTitles)) {
+			continue;
+		}
+
+		const concepts = extractConcepts(sentence);
+
+		// Parse distillation terms for additional concepts
+		let distTerms: string[] = [];
+		try {
+			distTerms = JSON.parse(distillation.terms);
+		} catch {
+			// Invalid JSON, skip
+		}
+
+		// Merge concepts from sentence + distillation terms (max 8)
+		const allConcepts = [
+			...new Set([...concepts, ...distTerms.slice(0, 3)]),
+		].slice(0, 8);
+
+		return {
+			type,
+			title,
+			narrative: sentence,
+			concepts: allConcepts,
+			confidence: MEMORY_CONFIG.curator.defaultConfidence,
+			source: "curator",
+		};
+	}
+
+	return null;
+}

package/dist/template/.opencode/plugin/lib/db/graph.ts

@@ -0,0 +1,253 @@
+/**
+ * Entity Graph Operations (v3)
+ *
+ * Temporal knowledge graph backed by SQLite entity_triples table.
+ * Supports time-aware queries (as_of), invalidation, and entity timeline.
+ *
+ * Inspired by MemPalace's temporal KG pattern: facts have valid_from/valid_to
+ * dates, enabling "what was true on date X?" queries.
+ */
+
+import { getMemoryDB } from "./schema.js";
+import type {
+	EntityQueryResult,
+	EntityTripleInput,
+	EntityTripleRow,
+} from "./types.js";
+
+// ============================================================================
+// CRUD
+// ============================================================================
+
+/**
+ * Add a new entity triple to the knowledge graph.
+ */
+export function addEntityTriple(input: EntityTripleInput): number {
+	const db = getMemoryDB();
+	const now = new Date();
+
+	const validFrom = input.valid_from ?? now.toISOString().slice(0, 10);
+
+	const result = db
+		.query(
+			`INSERT INTO entity_triples
+       (subject, predicate, object, valid_from, valid_to, confidence, source_observation_id, created_at, created_at_epoch)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+		)
+		.run(
+			input.subject.toLowerCase().trim(),
+			input.predicate.toLowerCase().trim(),
+			input.object.toLowerCase().trim(),
+			validFrom,
+			input.valid_to ?? null,
+			input.confidence ?? 1.0,
+			input.source_observation_id ?? null,
+			now.toISOString(),
+			now.getTime(),
+		);
+
+	return Number(result.lastInsertRowid);
+}
+
+/**
+ * Invalidate a triple by setting its valid_to date.
+ * Finds active triples matching subject+predicate+object and closes them.
+ */
+export function invalidateTriple(
+	subject: string,
+	predicate: string,
+	object: string,
+	endDate?: string,
+): number {
+	const db = getMemoryDB();
+	const validTo = endDate ?? new Date().toISOString().slice(0, 10);
+
+	const result = db.run(
+		`UPDATE entity_triples
+     SET valid_to = ?
+     WHERE LOWER(subject) = LOWER(?) AND LOWER(predicate) = LOWER(?) AND LOWER(object) = LOWER(?)
+       AND valid_to IS NULL`,
+		[validTo, subject.trim(), predicate.trim(), object.trim()],
+	);
+
+	return result.changes;
+}
+
+/**
+ * Get a triple by ID.
+ */
+export function getTripleById(id: number): EntityTripleRow | null {
+	const db = getMemoryDB();
+	return db
+		.query("SELECT * FROM entity_triples WHERE id = ?")
+		.get(id) as EntityTripleRow | null;
+}
+
+// ============================================================================
+// Queries
+// ============================================================================
+
+/**
+ * Query entity relationships with optional time filtering.
+ * Returns triples where entity appears as subject or object.
+ */
+export function queryEntity(
+	entity: string,
+	options: {
+		as_of?: string; // ISO date — filter to triples valid at this time
+		direction?: "out" | "in" | "both"; // out = subject, in = object, both = either
+		predicate?: string; // filter by predicate
+		activeOnly?: boolean; // only return currently active triples
+		limit?: number;
+	} = {},
+): EntityQueryResult[] {
+	const db = getMemoryDB();
+	const direction = options.direction ?? "both";
+	const limit = options.limit ?? 50;
+	const entityLower = entity.toLowerCase().trim();
+
+	const conditions: string[] = [];
+	const params: (string | number)[] = [];
+
+	// Direction filter
+	if (direction === "out") {
+		conditions.push("LOWER(subject) = ?");
+		params.push(entityLower);
+	} else if (direction === "in") {
+		conditions.push("LOWER(object) = ?");
+		params.push(entityLower);
+	} else {
+		conditions.push("(LOWER(subject) = ? OR LOWER(object) = ?)");
+		params.push(entityLower, entityLower);
+	}
+
+	// Predicate filter
+	if (options.predicate) {
+		conditions.push("LOWER(predicate) = ?");
+		params.push(options.predicate.toLowerCase().trim());
+	}
+
+	// Time filter
+	if (options.as_of) {
+		conditions.push("valid_from <= ?");
+		params.push(options.as_of);
+		conditions.push("(valid_to IS NULL OR valid_to >= ?)");
+		params.push(options.as_of);
+	} else if (options.activeOnly) {
+		conditions.push("valid_to IS NULL");
+	}
+
+	params.push(limit);
+
+	const sql = `
+    SELECT id, subject, predicate, object, valid_from, valid_to, confidence,
+           CASE WHEN valid_to IS NULL THEN 1 ELSE 0 END as is_active
+    FROM entity_triples
+    WHERE ${conditions.join(" AND ")}
+    ORDER BY valid_from DESC, created_at_epoch DESC
+    LIMIT ?
+  `;
+
+	return db.query(sql).all(...params) as EntityQueryResult[];
+}
+
+/**
+ * Get entity timeline — all triples involving an entity, sorted chronologically.
+ */
+export function getEntityTimeline(
+	entity: string,
+	options: { limit?: number } = {},
+): EntityTripleRow[] {
+	const db = getMemoryDB();
+	const limit = options.limit ?? 100;
+	const entityLower = entity.toLowerCase().trim();
+
+	return db
+		.query(
+			`SELECT * FROM entity_triples
+       WHERE LOWER(subject) = ? OR LOWER(object) = ?
+       ORDER BY valid_from ASC, created_at_epoch ASC
+       LIMIT ?`,
+		)
+		.all(entityLower, entityLower, limit) as EntityTripleRow[];
+}
+
+/**
+ * Find contradictions: active triples with opposing predicates for same subject-object pair.
+ */
+export function findContradictions(
+	subject: string,
+	predicate: string,
+	object: string,
+): EntityTripleRow[] {
+	const db = getMemoryDB();
+
+	return db
+		.query(
+			`SELECT * FROM entity_triples
+       WHERE LOWER(subject) = LOWER(?) AND LOWER(object) = LOWER(?)
+         AND LOWER(predicate) != LOWER(?)
+         AND valid_to IS NULL
+       ORDER BY created_at_epoch DESC`,
+		)
+		.all(subject.trim(), object.trim(), predicate.trim()) as EntityTripleRow[];
+}
+
+// ============================================================================
+// Stats
+// ============================================================================
+
+/**
+ * Get entity graph statistics.
+ */
+export function getEntityGraphStats(): {
+	total_triples: number;
+	active_triples: number;
+	unique_entities: number;
+	unique_predicates: number;
+} {
+	const db = getMemoryDB();
+
+	const total = (
+		db.query("SELECT COUNT(*) as count FROM entity_triples").get() as {
+			count: number;
+		}
+	).count;
+
+	const active = (
+		db
+			.query(
+				"SELECT COUNT(*) as count FROM entity_triples WHERE valid_to IS NULL",
+			)
+			.get() as {
+			count: number;
+		}
+	).count;
+
+	const entities = (
+		db
+			.query(
+				`SELECT COUNT(DISTINCT entity) as count FROM (
+           SELECT subject as entity FROM entity_triples
+           UNION ALL
+           SELECT object as entity FROM entity_triples
+         )`,
+			)
+			.get() as { count: number }
+	).count;
+
+	const predicates = (
+		db
+			.query("SELECT COUNT(DISTINCT predicate) as count FROM entity_triples")
+			.get() as {
+			count: number;
+		}
+	).count;
+
+	return {
+		total_triples: total,
+		active_triples: active,
+		unique_entities: entities,
+		unique_predicates: predicates,
+	};
+}