opencodekit 0.20.2 → 0.20.4

package/dist/template/.opencode/plugin/README.md

@@ -41,7 +41,7 @@ plugin/
   - Injects relevant knowledge into system prompt (BM25 _ recency _ confidence scoring)
   - Manages context window via messages.transform (token budget enforcement)
   - Merges compaction logic (beads, handoffs, project memory, knowledge)
-  - Provides 7 tools: observation, memory-search, memory-get, memory-read, memory-update, memory-timeline, memory-admin
+  - Provides 11 tools: observation, memory-search, memory-get, memory-read, memory-update, memory-timeline, memory-graph-add, memory-graph-query, memory-graph-invalidate, memory-compact, memory-admin
 
 - `sessions.ts`
   - Provides tools: `find_sessions`, `read_session`

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,
+	};
+}
+

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,
+	};
+}