opencodekit 0.20.2 → 0.20.4

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

@@ -0,0 +1,359 @@
+/**
+ * Memory Lint — Self-Healing Knowledge Base
+ *
+ * Inspired by Karpathy's LLM Wiki "lint" operation:
+ * scans observations for duplicates, contradictions, stale claims,
+ * orphan concepts, and missing cross-references.
+ *
+ * Returns structured issues for human or automated resolution.
+ */
+
+import type { ObservationRow } from "./db/types.js";
+import { getMemoryDB } from "./memory-db.js";
+import { hasWord, parseConcepts } from "./memory-helpers.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type LintIssueType =
+	| "duplicate"
+	| "contradiction"
+	| "stale"
+	| "orphan"
+	| "missing-narrative";
+
+export interface LintIssue {
+	type: LintIssueType;
+	severity: "high" | "medium" | "low";
+	observation_ids: number[];
+	title: string;
+	detail: string;
+	suggestion: string;
+}
+
+export interface LintResult {
+	issues: LintIssue[];
+	stats: {
+		total_observations: number;
+		duplicates: number;
+		contradictions: number;
+		stale: number;
+		orphans: number;
+		missing_narrative: number;
+	};
+}
+
+// ============================================================================
+// Core Lint Operations
+// ============================================================================
+
+/**
+ * Run all lint checks and return a consolidated report.
+ */
+export function lintMemory(options: { staleDays?: number } = {}): LintResult {
+	const staleDays = options.staleDays ?? 90;
+	const issues: LintIssue[] = [];
+
+	const duplicates = findDuplicates();
+	const contradictions = findContradictions();
+	const stale = findStaleObservations(staleDays);
+	const orphans = findOrphanObservations();
+	const missing = findMissingNarratives();
+
+	issues.push(
+		...duplicates,
+		...contradictions,
+		...stale,
+		...orphans,
+		...missing,
+	);
+
+	// Count total active observations
+	const db = getMemoryDB();
+	const row = db
+		.query(
+			"SELECT COUNT(*) as count FROM observations WHERE superseded_by IS NULL",
+		)
+		.get() as { count: number };
+
+	return {
+		issues,
+		stats: {
+			total_observations: row.count,
+			duplicates: duplicates.length,
+			contradictions: contradictions.length,
+			stale: stale.length,
+			orphans: orphans.length,
+			missing_narrative: missing.length,
+		},
+	};
+}
+
+/**
+ * Find observations with very similar titles (potential duplicates).
+ * Uses normalized title comparison + concept overlap.
+ */
+function findDuplicates(): LintIssue[] {
+	const db = getMemoryDB();
+	const issues: LintIssue[] = [];
+
+	const observations = db
+		.query(
+			"SELECT id, type, title, concepts, narrative FROM observations WHERE superseded_by IS NULL ORDER BY created_at_epoch DESC",
+		)
+		.all() as Pick<
+		ObservationRow,
+		"id" | "type" | "title" | "concepts" | "narrative"
+	>[];
+
+	// Group by normalized title
+	const titleMap = new Map<string, typeof observations>();
+	for (const obs of observations) {
+		const normalized = normalizeTitle(obs.title);
+		const group = titleMap.get(normalized) ?? [];
+		group.push(obs);
+		titleMap.set(normalized, group);
+	}
+
+	for (const [normalized, group] of titleMap) {
+		if (group.length > 1) {
+			issues.push({
+				type: "duplicate",
+				severity: "medium",
+				observation_ids: group.map((o) => o.id),
+				title: `Duplicate: "${group[0].title}"`,
+				detail: `${group.length} observations with similar title "${normalized}": IDs ${group.map((o) => `#${o.id}`).join(", ")}`,
+				suggestion: `Use \`observation({ supersedes: "${group[group.length - 1].id}" })\` to merge, keeping the most recent.`,
+			});
+		}
+	}
+
+	// Also check concept overlap for same-type observations
+	const byType = new Map<string, typeof observations>();
+	for (const obs of observations) {
+		if (!obs.concepts) continue;
+		const group = byType.get(obs.type) ?? [];
+		group.push(obs);
+		byType.set(obs.type, group);
+	}
+
+	for (const [, group] of byType) {
+		for (let i = 0; i < group.length; i++) {
+			for (let j = i + 1; j < group.length; j++) {
+				const overlap = conceptOverlap(group[i].concepts, group[j].concepts);
+				if (overlap > 0.8 && group[i].id !== group[j].id) {
+					// Check not already flagged by title
+					const alreadyFlagged = issues.some(
+						(iss) =>
+							iss.type === "duplicate" &&
+							iss.observation_ids.includes(group[i].id) &&
+							iss.observation_ids.includes(group[j].id),
+					);
+					if (!alreadyFlagged) {
+						issues.push({
+							type: "duplicate",
+							severity: "low",
+							observation_ids: [group[i].id, group[j].id],
+							title: `High concept overlap: #${group[i].id} ↔ #${group[j].id}`,
+							detail: `"${group[i].title}" and "${group[j].title}" share ${(overlap * 100).toFixed(0)}% concepts`,
+							suggestion: `Review if these should be merged with \`supersedes\`.`,
+						});
+					}
+				}
+			}
+		}
+	}
+
+	return issues;
+}
+
+/**
+ * Find observations of the same type/concepts that may contradict each other.
+ * Looks for opposing signal words in narratives.
+ */
+function findContradictions(): LintIssue[] {
+	const db = getMemoryDB();
+	const issues: LintIssue[] = [];
+
+	// Get decision-type observations that share concepts
+	const decisions = db
+		.query(
+			`SELECT id, title, concepts, narrative FROM observations
+			 WHERE type = 'decision' AND superseded_by IS NULL AND concepts IS NOT NULL`,
+		)
+		.all() as Pick<ObservationRow, "id" | "title" | "concepts" | "narrative">[];
+
+	// Check pairs for contradictory language
+	const contradictionPairs = [
+		["use", "don't use"],
+		["enable", "disable"],
+		["add", "remove"],
+		["prefer", "avoid"],
+		["always", "never"],
+		["yes", "no"],
+	];
+
+	for (let i = 0; i < decisions.length; i++) {
+		for (let j = i + 1; j < decisions.length; j++) {
+			const overlap = conceptOverlap(
+				decisions[i].concepts,
+				decisions[j].concepts,
+			);
+			if (overlap < 0.3) continue; // Unrelated decisions
+
+			const textA =
+				`${decisions[i].title} ${decisions[i].narrative ?? ""}`.toLowerCase();
+			const textB =
+				`${decisions[j].title} ${decisions[j].narrative ?? ""}`.toLowerCase();
+
+			for (const [wordA, wordB] of contradictionPairs) {
+				if (
+					(hasWord(textA, wordA) && hasWord(textB, wordB)) ||
+					(hasWord(textA, wordB) && hasWord(textB, wordA))
+				) {
+					issues.push({
+						type: "contradiction",
+						severity: "high",
+						observation_ids: [decisions[i].id, decisions[j].id],
+						title: `Potential contradiction: #${decisions[i].id} vs #${decisions[j].id}`,
+						detail: `"${decisions[i].title}" and "${decisions[j].title}" share concepts but contain opposing signals ("${wordA}" vs "${wordB}")`,
+						suggestion: `Review both and supersede the outdated one.`,
+					});
+					break; // One contradiction signal per pair is enough
+				}
+			}
+		}
+	}
+
+	return issues;
+}
+
+/**
+ * Find observations older than N days with no references in recent distillations.
+ */
+function findStaleObservations(staleDays: number): LintIssue[] {
+	const db = getMemoryDB();
+	const cutoffEpoch = Date.now() - staleDays * 24 * 60 * 60 * 1000;
+
+	const stale = db
+		.query(
+			`SELECT id, type, title, created_at, created_at_epoch FROM observations
+			 WHERE superseded_by IS NULL AND created_at_epoch < ? AND valid_until IS NULL
+			 ORDER BY created_at_epoch ASC`,
+		)
+		.all(cutoffEpoch) as Pick<
+		ObservationRow,
+		"id" | "type" | "title" | "created_at" | "created_at_epoch"
+	>[];
+
+	return stale.map((obs) => {
+		const ageDays = Math.floor(
+			(Date.now() - obs.created_at_epoch) / (1000 * 60 * 60 * 24),
+		);
+		return {
+			type: "stale" as const,
+			severity:
+				ageDays > staleDays * 2 ? ("high" as const) : ("medium" as const),
+			observation_ids: [obs.id],
+			title: `Stale (${ageDays}d): #${obs.id} "${obs.title}"`,
+			detail: `[${obs.type}] created ${obs.created_at.slice(0, 10)}, ${ageDays} days old with no valid_until set`,
+			suggestion: `Review: still relevant? If yes, update it. If no, supersede or set valid_until.`,
+		};
+	});
+}
+
+/**
+ * Find observations with concepts that appear in only one observation.
+ * These are "orphan concepts" — knowledge islands with no connections.
+ */
+function findOrphanObservations(): LintIssue[] {
+	const db = getMemoryDB();
+	const issues: LintIssue[] = [];
+
+	const observations = db
+		.query(
+			"SELECT id, title, concepts FROM observations WHERE superseded_by IS NULL AND concepts IS NOT NULL",
+		)
+		.all() as Pick<ObservationRow, "id" | "title" | "concepts">[];
+
+	// Build concept → observation IDs map
+	const conceptMap = new Map<string, number[]>();
+	for (const obs of observations) {
+		const concepts = parseConcepts(obs.concepts);
+		for (const concept of concepts) {
+			const ids = conceptMap.get(concept) ?? [];
+			ids.push(obs.id);
+			conceptMap.set(concept, ids);
+		}
+	}
+
+	// Find observations where ALL concepts are orphans (only appear once)
+	for (const obs of observations) {
+		const concepts = parseConcepts(obs.concepts);
+		if (concepts.length === 0) continue;
+		const allOrphan = concepts.every(
+			(c) => (conceptMap.get(c)?.length ?? 0) <= 1,
+		);
+		if (allOrphan && concepts.length >= 2) {
+			issues.push({
+				type: "orphan",
+				severity: "low",
+				observation_ids: [obs.id],
+				title: `Isolated: #${obs.id} "${obs.title}"`,
+				detail: `All concepts [${concepts.join(", ")}] appear in no other observation — this knowledge is disconnected`,
+				suggestion: `Consider adding cross-references or broadening concept tags.`,
+			});
+		}
+	}
+
+	return issues;
+}
+
+/**
+ * Find observations with no narrative (title-only, low value).
+ */
+function findMissingNarratives(): LintIssue[] {
+	const db = getMemoryDB();
+
+	const missing = db
+		.query(
+			`SELECT id, type, title FROM observations
+			 WHERE superseded_by IS NULL AND (narrative IS NULL OR narrative = '')`,
+		)
+		.all() as Pick<ObservationRow, "id" | "type" | "title">[];
+
+	return missing.map((obs) => ({
+		type: "missing-narrative" as const,
+		severity: "low" as const,
+		observation_ids: [obs.id],
+		title: `No narrative: #${obs.id} "${obs.title}"`,
+		detail: `[${obs.type}] has title but no narrative — low-value observation`,
+		suggestion: `Add narrative context or remove if the title alone is not useful.`,
+	}));
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function normalizeTitle(title: string): string {
+	return title
+		.toLowerCase()
+		.replace(/[^a-z0-9\s]/g, "")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+function conceptOverlap(a: string | null, b: string | null): number {
+	const conceptsA = new Set(parseConcepts(a));
+	const conceptsB = new Set(parseConcepts(b));
+	if (conceptsA.size === 0 || conceptsB.size === 0) return 0;
+
+	let overlap = 0;
+	for (const c of conceptsA) {
+		if (conceptsB.has(c)) overlap++;
+	}
+	return overlap / Math.min(conceptsA.size, conceptsB.size);
+}
+

package/dist/template/.opencode/plugin/lib/memory-admin-tools.ts

@@ -1,7 +1,7 @@
 /**
  * Memory Plugin — Admin Tools
  *
- * memory-admin (9 operations).
+ * memory-admin (12 operations).
  *
  * Uses factory pattern: createAdminTools(deps) returns tool definitions.
  */
@@ -10,16 +10,23 @@ import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { tool } from "@opencode-ai/plugin/tool";
 import { curateFromDistillations } from "./curator.js";
+import { compileObservations } from "./compile.js";
 import { distillSession } from "./distill.js";
+import { generateMemoryIndex } from "./index-generator.js";
+import { lintMemory } from "./lint.js";
+import { getLogContent } from "./operation-log.js";
 import {
 	archiveOldObservations,
 	type ConfidenceLevel,
 	checkFTS5Available,
 	checkpointWAL,
+	findGraphContradictions,
 	getCaptureStats,
 	getDatabaseSizes,
 	getDistillationStats,
+	getEntityGraphStats,
 	getMarkdownFilesInSqlite,
+	getMemoryDB,
 	getObservationStats,
 	type ObservationType,
 	rebuildFTS5,
@@ -37,7 +44,7 @@ export function createAdminTools(deps: AdminToolDeps) {
 
 	return {
 		"memory-admin": tool({
-			description: `Memory system administration: maintenance and migration.\n\nOperations:\n- "status": Storage stats and recommendations\n- "full": Full maintenance cycle (archive + checkpoint + vacuum)\n- "archive": Archive old observations (>90 days default)\n- "checkpoint": Checkpoint WAL file\n- "vacuum": Vacuum database\n- "migrate": Import .opencode/memory/observations/*.md into SQLite\n- "capture-stats": Temporal message capture statistics\n- "distill-now": Force distillation for current session\n- "curate-now": Force curator run\n\nExample:\nmemory-admin({ operation: "status" })\nmemory-admin({ operation: "migrate", dry_run: true })`,
+			description: `Memory system administration: maintenance and migration.\n\nOperations:\n- "status": Storage stats and recommendations\n- "full": Full maintenance cycle (archive + checkpoint + vacuum)\n- "archive": Archive old observations (>90 days default)\n- "checkpoint": Checkpoint WAL file\n- "vacuum": Vacuum database\n- "migrate": Import .opencode/memory/observations/*.md into SQLite\n- "capture-stats": Temporal message capture statistics\n- "distill-now": Force distillation for current session\n- "curate-now": Force curator run\n- "lint": Run lint checks (duplicates, contradictions, stale, orphans)\n- "index": Generate memory index catalog\n- "compile": Compile observations into structured articles\n- "log": View operation log\n\nExample:\nmemory-admin({ operation: "status" })\nmemory-admin({ operation: "migrate", dry_run: true })\nmemory-admin({ operation: "lint" })\nmemory-admin({ operation: "compile" })`,
 			args: {
 				operation: tool.schema
 					.string()
@@ -69,11 +76,12 @@ export function createAdminTools(deps: AdminToolDeps) {
 							});
 							const captureStats = getCaptureStats();
 							const distillStats = getDistillationStats();
+							const graphStats = getEntityGraphStats();
 							return [
 								"## Memory System Status\n",
 								`**Database**: ${(sizes.total / 1024).toFixed(1)} KB`,
 								`**FTS5**: ${checkFTS5Available() ? "Available (porter stemming)" : "Unavailable"}`,
-								`**Schema**: v2 (4-tier storage)\n`,
+								`**Schema**: v3 (4-tier + entity graph)\n`,
 								"### Observations",
 								...Object.entries(stats).map(([k, v]) => `  ${k}: ${v}`),
 								`  Archivable (>${olderThanDays}d): ${archivable}\n`,
@@ -82,7 +90,11 @@ export function createAdminTools(deps: AdminToolDeps) {
 								`  Sessions: ${captureStats.sessions}\n`,
 								"### Distillations",
 								`  Total: ${distillStats.total} (${distillStats.sessions} sessions)`,
-								`  Avg compression: ${(distillStats.avgCompression * 100).toFixed(1)}%`,
+								`  Avg compression: ${(distillStats.avgCompression * 100).toFixed(1)}%\n`,
+								"### Entity Graph",
+								`  Triples: ${graphStats.total_triples} (active: ${graphStats.active_triples})`,
+								`  Entities: ${graphStats.unique_entities}`,
+								`  Predicates: ${graphStats.unique_predicates}`,
 							].join("\n");
 						}
 						case "full": {
@@ -126,6 +138,68 @@ export function createAdminTools(deps: AdminToolDeps) {
 							const r = curateFromDistillations();
 							return `Created ${r.created}, skipped ${r.skipped}. Patterns: ${JSON.stringify(r.patterns)}`;
 						}
+						case "lint": {
+							const result = lintMemory({ staleDays: olderThanDays });
+
+							// Entity graph contradiction scan
+							const graphStats = getEntityGraphStats();
+							if (graphStats.total_triples > 0) {
+								try {
+									// Check each active triple for contradictions
+									const db = getMemoryDB();
+									const activeTriples = db.query(
+										"SELECT DISTINCT subject, predicate, object FROM entity_triples WHERE valid_to IS NULL LIMIT 200"
+									).all() as { subject: string; predicate: string; object: string }[];
+									for (const t of activeTriples) {
+										const contradictions = findGraphContradictions(t.subject, t.predicate, t.object);
+										if (contradictions.length > 0) {
+											result.issues.push({
+												severity: "medium" as const,
+												title: `Graph contradiction: ${t.subject} ↔ ${t.object}`,
+												detail: `Active triple "${t.subject} —[${t.predicate}]→ ${t.object}" has ${contradictions.length} conflicting predicate(s): ${contradictions.map(c => c.predicate).join(", ")}`,
+												suggestion: `Use memory-graph-invalidate to close outdated triples`,
+												type: "contradiction" as const,
+												observation_ids: contradictions.map(c => c.source_observation_id).filter((id): id is number => id != null),
+											});
+										}
+									}
+								} catch { /* Graph table may not exist yet */ }
+							}
+							if (result.issues.length === 0) {
+								return `Memory lint: clean (${result.stats.total_observations} observations, 0 issues).`;
+							}
+							const lines: string[] = [
+								`## Memory Lint Report\n`,
+								`**${result.issues.length} issues** found in ${result.stats.total_observations} observations:\n`,
+								`| Duplicates | Contradictions | Stale | Orphans | Missing Narrative |`,
+								`|---|---|---|---|---|`,
+								`| ${result.stats.duplicates} | ${result.stats.contradictions} | ${result.stats.stale} | ${result.stats.orphans} | ${result.stats.missing_narrative} |\n`,
+							];
+							for (const issue of result.issues.slice(0, 15)) {
+								lines.push(`- **[${issue.severity}]** ${issue.title}`);
+								lines.push(`  ${issue.detail}`);
+								lines.push(`  _Suggestion: ${issue.suggestion}_\n`);
+							}
+							if (result.issues.length > 15) {
+								lines.push(`... and ${result.issues.length - 15} more issues.`);
+							}
+							return lines.join("\n");
+						}
+						case "index": {
+							const result = generateMemoryIndex();
+							return `Index generated: ${result.entryCount} observations, ${result.conceptCount} concepts. Read with \`memory-read({ file: "index" })\`.`;
+						}
+						case "compile": {
+							const result = compileObservations();
+							if (result.articles.length === 0) {
+								return `No concept clusters with 3+ observations found. Nothing to compile.`;
+							}
+							const articleList = result.articles.map(a => `  - ${a.concept} (${a.observationCount} obs)`).join("\n");
+							return `Compiled ${result.articles.length} articles from ${result.totalObservations} observations (${result.skippedClusters} skipped).\n\nArticles:\n${articleList}\n\nRead with \`memory-read({ file: "compiled/<concept>" })\`.`;
+						}
+						case "log": {
+							return getLogContent();
+						}
 						case "migrate": {
 							const obsDir = path.join(
 								directory,

package/dist/template/.opencode/plugin/lib/memory-db.ts

@@ -1,5 +1,5 @@
 /**
- * Memory Database Module v2 — Barrel Export
+ * Memory Database Module v3 — Barrel Export
  *
  * Re-exports all functions and types from sub-modules in ./db/.
  * This preserves backward compatibility for existing imports from "./lib/memory-db.js".
@@ -10,6 +10,7 @@
  *   db/observations.ts — Observation CRUD, search, timeline, stats
  *   db/pipeline.ts     — Temporal messages, distillations, relevance scoring
  *   db/maintenance.ts  — Memory files, FTS5, DB maintenance
+ *   db/graph.ts        — Entity graph: temporal triples, queries, stats
  */
 
 // Memory Files, FTS5, and Maintenance
@@ -52,7 +53,24 @@ export {
 	storeDistillation,
 	storeTemporalMessage,
 } from "./db/pipeline.js";
+// Entity Graph Operations (v3)
+export {
+	addEntityTriple,
+	findContradictions as findGraphContradictions,
+	getEntityGraphStats,
+	getEntityTimeline,
+	getTripleById,
+	invalidateTriple,
+	queryEntity,
+} from "./db/graph.js";
 // Database Manager
 export { closeMemoryDB, getMemoryDB } from "./db/schema.js";
 // Types & Configuration
 export * from "./db/types.js";
+
+// New modules (v2.1: lint, compile, index, validate, operation log)
+export { lintMemory, type LintResult, type LintIssue, type LintIssueType } from "./lint.js";
+export { generateMemoryIndex, type IndexResult, type IndexEntry } from "./index-generator.js";
+export { appendOperationLog, getRecentLogEntries, getLogContent, type LogEntry, type OperationType } from "./operation-log.js";
+export { compileObservations, type CompileResult, type CompiledArticle, type ConceptCluster } from "./compile.js";
+export { validateObservation, type ValidationResult, type ValidationVerdict, type ValidationIssue } from "./validate.js";

package/dist/template/.opencode/plugin/lib/memory-helpers.ts

@@ -75,6 +75,36 @@ export function parseCSV(value: string | undefined): string[] | undefined {
 		.filter((s) => s.length > 0);
 }
 
+/**
+ * Parse a concepts field (JSON array or CSV string) into normalized strings.
+ * Handles both `["a","b"]` JSON and `"a, b"` CSV formats.
+ */
+export function parseConcepts(raw: string | null): string[] {
+	if (!raw) return [];
+	try {
+		const parsed = JSON.parse(raw);
+		if (Array.isArray(parsed))
+			return parsed.map((c: string) => c.toLowerCase().trim());
+		// JSON.parse succeeded but not an array (e.g., a plain string) — fall through to CSV
+	} catch {
+		// Not JSON — fall through to CSV
+	}
+	return raw
+		.split(",")
+		.map((c) => c.toLowerCase().trim())
+		.filter((c) => c.length > 0);
+}
+
+/**
+ * Check if a word appears in text with word-boundary matching.
+ * Prevents false positives from substring matches (e.g., "use" in "because").
+ */
+export function hasWord(text: string, word: string): boolean {
+	return new RegExp(`\\b${word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i").test(
+		text,
+	);
+}
+
 export function formatObservation(obs: {
 	id: number;
 	type: string;

package/dist/template/.opencode/plugin/lib/memory-hooks.ts

@@ -15,9 +15,11 @@
  */
 
 import { captureMessageMeta, captureMessagePart } from "./capture.js";
+import { compileObservations } from "./compile.js";
 import { manageContext } from "./context.js";
 import { curateFromDistillations } from "./curator.js";
 import { distillSession } from "./distill.js";
+import { generateMemoryIndex } from "./index-generator.js";
 import { buildInjection } from "./inject.js";
 import {
 	checkFTS5Available,
@@ -128,6 +130,14 @@ export function createHooks(deps: HookDeps) {
 					if (checkFTS5Available()) optimizeFTS5();
 					const sizes = getDatabaseSizes();
 					if (sizes.wal > 1024 * 1024) checkpointWAL();
+
+					// Compile & index on idle (lightweight, after curation)
+					try {
+						compileObservations({ minObservations: 3, maxArticles: 10 });
+						generateMemoryIndex();
+					} catch {
+						/* Non-fatal: compile/index are nice-to-have */
+					}
 				} catch (err) {
 					const msg = err instanceof Error ? err.message : String(err);
 					await log(`Idle maintenance failed: ${msg}`, "warn");