opencodekit 0.17.13 → 0.18.1

package/dist/template/.opencode/skill/memory-system/SKILL.md

@@ -5,7 +5,29 @@ description: Use when persisting learnings, loading previous context, or searchi
 
 # Memory System Best Practices
 
-Persistent context that survives across sessions. Uses **SQLite + FTS5** for searchable observations.
+Persistent context that survives across sessions. Uses **4-tier automated knowledge pipeline** backed by SQLite + FTS5.
+
+## Architecture
+
+```
+message.part.updated → capture.ts → temporal_messages
+                                        ↓ (session.idle, 10+ messages)
+                                     distill.ts → distillations (TF-IDF + key sentences)
+                                        ↓ (session.idle)
+                                     curator.ts → observations (pattern-matched)
+                                        ↓
+system.transform ← inject.ts ← FTS5 search → scored + packed → system prompt
+messages.transform ← context.ts → token budget enforcement
+```
+
+### 4 Tiers
+
+| Tier              | Storage       | Populated By        | Purpose                         |
+| ----------------- | ------------- | ------------------- | ------------------------------- |
+| temporal_messages | SQLite        | Automatic (capture) | Raw message text, 180-day TTL   |
+| distillations     | SQLite + FTS5 | Automatic (idle)    | TF-IDF compressed sessions      |
+| observations      | SQLite + FTS5 | Manual + curator    | Decisions, bugs, patterns, etc. |
+| memory_files      | SQLite        | Manual              | Static docs, handoffs, research |
 
 ## Core Principle
 
@@ -23,11 +45,11 @@ Always search memory first.
 
 ```typescript
 // Search for relevant past work
-memory_search({ query: "<task keywords>", limit: 5 });
-memory_search({ query: "bugfix <component>", type: "observations" });
+memory - search({ query: "<task keywords>", limit: 5 });
+memory - search({ query: "bugfix <component>", type: "observations" });
 
 // Check recent handoffs
-memory_search({ query: "handoff", type: "handoffs", limit: 3 });
+memory - search({ query: "handoff", type: "handoffs", limit: 3 });
 ```
 
 **Why:** Past you already solved this. Don't rediscover.
@@ -38,14 +60,14 @@ Don't fetch full content until you know you need it.
 
 ```typescript
 // 1. Search returns compact index (50-100 tokens per result)
-const results = memory_search({ query: "auth patterns" });
+const results = memory - search({ query: "auth patterns" });
 // Returns: [{id: 42, title: "Auth bug fixed", ...}]
 
 // 2. Fetch full details ONLY for relevant IDs
-memory_get({ ids: "42,45" });
+memory - get({ ids: "42,45" });
 
 // 3. See what led to this decision
-memory_timeline({ anchor_id: 42, depth_before: 3 });
+memory - timeline({ anchor_id: 42, depth_before: 3 });
 ```
 
 **Why:** Prevents context bloat. High signal, low noise.
@@ -56,12 +78,13 @@ Create observations for anything non-obvious. Don't wait until the end.
 
 ```typescript
 observation({
-  type: "pattern", // decision | bugfix | pattern | discovery | warning
+  type: "pattern", // decision | bugfix | pattern | discovery | warning | learning
   title: "Brief description",
   narrative: "Context and reasoning...",
   facts: "key, facts, here",
   concepts: "searchable, keywords",
   files_modified: "src/file.ts",
+  source: "manual", // manual (default) | curator | imported
 });
 ```
 
@@ -79,9 +102,10 @@ observation({
 Document completion state for future you.
 
 ```typescript
-memory_update({
-  file: "handoffs/YYYY-MM-DD-task",
-  content: `## Completed
+memory -
+  update({
+    file: "handoffs/YYYY-MM-DD-task",
+    content: `## Completed
 - X
 
 ## Blockers
@@ -89,8 +113,8 @@ memory_update({
 
 ## Next
 - Z`,
-  mode: "append",
-});
+    mode: "append",
+  });
 ```
 
 ---
@@ -99,18 +123,18 @@ memory_update({
 
 ### memory-search (Start Here)
 
-Fast FTS5 full-text search. Returns **compact index** for progressive disclosure.
+Fast FTS5 full-text search with porter stemming. Returns **compact index** for progressive disclosure.
 
 ```typescript
-memory_search({ query: "authentication" });
-memory_search({ query: "bugfix", type: "observations", limit: 5 });
-memory_search({ query: "session", type: "handoffs" });
-memory_search({ query: "patterns", type: "all" }); // Search everything
+memory - search({ query: "authentication" });
+memory - search({ query: "bugfix", type: "observations", limit: 5 });
+memory - search({ query: "session", type: "handoffs" });
+memory - search({ query: "patterns", type: "all" }); // Search everything
 ```
 
 **Search modes:**
 
-- `observations` (default): Search SQLite with FTS5 ranking
+- `observations` (default): Search SQLite with FTS5 BM25 ranking
 - `handoffs`, `research`, `templates`: Search specific directories
 - `beads`: Search .beads/artifacts
 - `all`: Search everything
@@ -120,8 +144,8 @@ memory_search({ query: "patterns", type: "all" }); // Search everything
 Fetch full observation details after identifying relevant IDs:
 
 ```typescript
-memory_get({ ids: "42" }); // Single observation
-memory_get({ ids: "1,5,10" }); // Multiple observations
+memory - get({ ids: "42" }); // Single observation
+memory - get({ ids: "1,5,10" }); // Multiple observations
 ```
 
 ### memory-timeline (Chronological Context)
@@ -129,7 +153,7 @@ memory_get({ ids: "1,5,10" }); // Multiple observations
 See what happened before/after a specific observation:
 
 ```typescript
-memory_timeline({ anchor_id: 42, depth_before: 5, depth_after: 5 });
+memory - timeline({ anchor_id: 42, depth_before: 5, depth_after: 5 });
 ```
 
 ### memory-read (Files)
@@ -137,9 +161,9 @@ memory_timeline({ anchor_id: 42, depth_before: 5, depth_after: 5 });
 Load project files, handoffs, or templates:
 
 ```typescript
-memory_read({ file: "project/gotchas" });
-memory_read({ file: "handoffs/2024-01-20-phase-1" });
-memory_read({ file: "research/auth-patterns" });
+memory - read({ file: "project/gotchas" });
+memory - read({ file: "handoffs/2024-01-20-phase-1" });
+memory - read({ file: "research/auth-patterns" });
 ```
 
 ### memory-update (Files)
@@ -147,13 +171,40 @@ memory_read({ file: "research/auth-patterns" });
 Save to project files or handoffs:
 
 ```typescript
-memory_update({
-  file: "project/gotchas",
-  content: "### New Gotcha\n\nDescription...",
-  mode: "append", // or "replace"
-});
+memory -
+  update({
+    file: "project/gotchas",
+    content: "### New Gotcha\n\nDescription...",
+    mode: "append", // or "replace"
+  });
+```
+
+### memory-admin (Maintenance)
+
+```typescript
+// Check current status (schema, FTS5, counts, DB size)
+memory - admin({ operation: "status" });
+
+// Full maintenance (archive >90 days, checkpoint WAL, vacuum)
+memory - admin({ operation: "full" });
+
+// Preview what would be archived
+memory - admin({ operation: "archive", older_than_days: 60, dry_run: true });
+
+// Capture pipeline stats (temporal messages, distillations, compression)
+memory - admin({ operation: "capture-stats" });
+
+// Force distillation for current session
+memory - admin({ operation: "distill-now" });
+
+// Force curator run (extract observations from distillations)
+memory - admin({ operation: "curate-now" });
 ```
 
+**Automatic:** On session idle — distillation, curation, FTS5 optimize, WAL checkpoint.
+
+**Manual:** Run `memory-admin({ operation: "status" })` to check health.
+
 ---
 
 ## What Goes Where
@@ -161,24 +212,34 @@ memory_update({
 ### SQLite (observations)
 
 - Events: decisions, bugfixes, patterns discovered
-- Searchable via FTS5
+- Searchable via FTS5 with porter stemming
+- Created manually via `observation()` or automatically by curator
 - Use `observation()` to create
 
+### SQLite (distillations — automatic)
+
+- Compressed session summaries with TF-IDF terms
+- Created automatically when 10+ messages accumulate
+- Searchable via FTS5
+- Used for relevance-scored LTM injection
+
 ### Markdown Files
 
 - Static knowledge: user preferences, tech stack
 - Handoffs: session summaries
 - Research: deep-dive documents
-- Use `memory_read()` / `memory_update()`
-
-| Location                   | Content                    | Tool                              |
-| -------------------------- | -------------------------- | --------------------------------- |
-| `project/user.md`          | User identity, preferences | `memory_read()`                   |
-| `project/tech-stack.md`    | Frameworks, constraints    | `memory_read()`                   |
-| `project/gotchas.md`       | Footguns, warnings         | `memory_update({mode: "append"})` |
-| `handoffs/YYYY-MM-DD-*.md` | Session summaries          | `memory_update()`                 |
-| `research/*.md`            | Deep-dive analysis         | `memory_update()`                 |
-| SQLite                     | Observations, events       | `observation()`                   |
+- Use `memory-read()` / `memory-update()`
+
+| Location                   | Content                    | Tool                                |
+| -------------------------- | -------------------------- | ----------------------------------- |
+| `project/user.md`          | User identity, preferences | `memory-read()`                     |
+| `project/tech-stack.md`    | Frameworks, constraints    | `memory-read()`                     |
+| `project/gotchas.md`       | Footguns, warnings         | `memory-update({ mode: "append" })` |
+| `handoffs/YYYY-MM-DD-*.md` | Session summaries          | `memory-update()`                   |
+| `research/*.md`            | Deep-dive analysis         | `memory-update()`                   |
+| SQLite observations        | Events, decisions          | `observation()`                     |
+| SQLite distillations       | Session summaries          | Automatic (idle) or `distill-now`   |
+| SQLite temporal_messages   | Raw captured text          | Automatic (message events)          |
 
 ---
 
@@ -195,6 +256,7 @@ observation({
   files_read: "src/auth.ts, src/middleware.ts",
   files_modified: "src/auth.ts",
   bead_id: "br-abc123", // Link to task (optional)
+  source: "manual", // manual (default), curator, imported
 });
 ```
 
@@ -213,25 +275,6 @@ observation({
 
 ---
 
-## Maintenance
-
-```typescript
-// Check current status
-memory_admin({ operation: "status" });
-
-// Full maintenance (archive >90 days, checkpoint WAL, vacuum)
-memory_admin({ operation: "full" });
-
-// Preview what would be archived
-memory_admin({ operation: "archive", older_than_days: 60, dry_run: true });
-```
-
-**Automatic:** Runs at session end (FTS5 optimize, WAL checkpoint if >1MB)
-
-**Manual:** Run monthly or when storage grows
-
----
-
 ## Philosophy
 
 **Memory is not a dumping ground. It's curated signal.**

package/dist/template/.opencode/skill/session-management/SKILL.md

@@ -19,48 +19,35 @@ The environment monitors context usage and warns at these thresholds:
 
 ## Session Tools
 
-### list_sessions
+### find_sessions
 
-Discover available sessions before reading:
+Search and discover sessions by keyword. Returns ranked results with match counts and snippets.
 
 ```typescript
-list_sessions({ limit: 10, project: "current" }); // Current project
-list_sessions({ since: "today" }); // Today's sessions
-list_sessions({ project: "all", since: "yesterday" }); // Cross-project
+find_sessions({ query: "auth bug", limit: 5 }); // Search by keyword
+find_sessions({ query: "refactor" }); // Default limit
 ```
 
-### read_session
+**Parameters:**
 
-Pull context from previous session:
+- `query` (required): Search keywords — multi-word queries use AND matching
+- `limit` (optional): Max results to return
 
-```typescript
-read_session("last"); // Most recent
-read_session("2 ago", { project: "current" }); // 2nd most recent
-read_session("today"); // Today's first session
-read_session("ses_abc123", { focus: "file changes" }); // Specific aspect
-```
+**Returns:** Ranked sessions with match count, snippets, and suggested next steps.
 
-### search_session
+### read_session
 
-Full-text search across sessions:
+Read messages from a specific session. Supports optional focus filtering.
 
 ```typescript
-search_session({ query: "auth bug" }); // Search all sessions
-search_session({ query: "OAuth", session_id: "ses_abc" }); // Specific session
-search_session({ query: "error", limit: 10 }); // Limit results
+read_session({ session_id: "ses_abc123" }); // Full session
+read_session({ session_id: "ses_abc123", focus: "auth" }); // Filter to relevant messages
 ```
 
-Use to find past discussions, decisions, or work on a topic before starting new work.
-
-### summarize_session
-
-Generate AI summary of a session:
-
-```typescript
-summarize_session("ses_abc123"); // Trigger AI summarization
-```
+**Parameters:**
 
-Use before `read_session` to get a quick overview of what happened in a past session without loading full context.
+- `session_id` (required): Session ID from find_sessions results
+- `focus` (optional): Keyword to filter messages within the session
 
 ## When to Start New Session
 
@@ -74,11 +61,11 @@ Use before `read_session` to get a quick overview of what happened in a past ses
 ```
 Session 1: Implement feature X (80k tokens)
   ↓ close, update memory
-Session 2: list_sessions() → read_session("last") → Refactor (60k tokens)
+Session 2: find_sessions({ query: "feature X" }) → read_session(...) → Refactor (60k tokens)
   ↓
-Session 3: read_session("previous") → Add tests (90k tokens)
+Session 3: find_sessions({ query: "feature X" }) → Add tests (90k tokens)
   ↓
-Session 4: read_session refs → Final review (100k tokens)
+Session 4: read_session(...) → Final review (100k tokens)
 ```
 
 **Result**: 4 fresh contexts vs 1 degraded 330k context. Better performance, lower cost.
@@ -87,10 +74,10 @@ Session 4: read_session refs → Final review (100k tokens)
 
 Use all available sources:
 
-1. `read_session("last")` - Previous session work
-2. Git state - `git diff`, `git log` - Code changes
-3. Memory files - `.opencode/memory/*` - Persistent context
-4. Beads - `br show <id>` - Task specs
+1. `find_sessions` + `read_session` — Previous session work
+2. Git state — `git diff`, `git log` — Code changes
+3. Memory files — `.opencode/memory/*` — Persistent context
+4. Beads — `br show <id>` — Task specs
 
 **Don't**: Carry everything forward. Extract what's needed, discard the rest.
 

package/dist/template/.opencode/tui.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "keybinds": {
+    "command_list": ";",
+    "leader": "`",
+    "session_child_cycle": "ctrl+alt+right",
+    "session_child_cycle_reverse": "ctrl+alt+left",
+    "session_compact": "ctrl+k"
+  },
+  "scroll_speed": 3,
+  "scroll_acceleration": {
+    "enabled": true
+  },
+  "diff_style": "auto"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.17.13",
+	"version": "0.18.1",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"keywords": ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
 	"license": "MIT",

package/dist/template/.opencode/plugin/compaction.ts

@@ -1,190 +0,0 @@
-/**
- * Session Continuity Plugin (compaction-time context injection)
- *
- * Purpose:
- * - Provide compact, bounded state needed to resume work after compaction.
- * - Keep injected prompt guidance minimal and deterministic.
- *
- * Non-goals:
- * - Replace DCP policy/rules management.
- * - Inject large free-form manuals into the prompt.
- */
-
-import { Database } from "bun:sqlite";
-import { readFile, readdir, stat } from "node:fs/promises";
-import path from "node:path";
-import type { Plugin } from "@opencode-ai/plugin";
-
-const MAX_SESSION_CONTEXT_CHARS = 3000;
-const MAX_PROJECT_FILES = 3;
-const MAX_PROJECT_FILE_CHARS = 900;
-const MAX_HANDOFF_CHARS = 2500;
-const MAX_BEADS = 8;
-const MAX_COMBINED_CONTEXT_CHARS = 9000;
-
-interface BeadRow {
-	id: string;
-	title: string;
-}
-
-function truncate(text: string, maxChars: number): string {
-	if (text.length <= maxChars) return text;
-	return `${text.slice(0, maxChars)}\n...[truncated]`;
-}
-
-async function safeReadFile(filePath: string): Promise<string> {
-	try {
-		return await readFile(filePath, "utf-8");
-	} catch {
-		return "";
-	}
-}
-
-function renderSection(title: string, body: string): string {
-	if (!body.trim()) return "";
-	return `## ${title}\n${body.trim()}`;
-}
-
-async function readProjectMemoryContext(memoryDir: string): Promise<string> {
-	const projectDir = path.join(memoryDir, "project");
-	let names: string[] = [];
-	try {
-		names = (await readdir(projectDir))
-			.filter((name) => name.endsWith(".md"))
-			.sort()
-			.slice(0, MAX_PROJECT_FILES);
-	} catch {
-		return "";
-	}
-
-	const chunks: string[] = [];
-	for (const name of names) {
-		const fullPath = path.join(projectDir, name);
-		const content = (await safeReadFile(fullPath)).trim();
-		if (!content) continue;
-		chunks.push(
-			`### ${name.replace(/\.md$/, "")}\n${truncate(content, MAX_PROJECT_FILE_CHARS)}`,
-		);
-	}
-
-	return chunks.join("\n\n");
-}
-
-async function readLatestHandoff(handoffDir: string): Promise<string> {
-	let names: string[] = [];
-	try {
-		names = (await readdir(handoffDir)).filter((name) => name.endsWith(".md"));
-	} catch {
-		return "";
-	}
-
-	if (names.length === 0) return "";
-
-	const withMtime = await Promise.all(
-		names.map(async (name) => {
-			const fullPath = path.join(handoffDir, name);
-			try {
-				const info = await stat(fullPath);
-				return { name, fullPath, mtimeMs: info.mtimeMs };
-			} catch {
-				return { name, fullPath, mtimeMs: 0 };
-			}
-		}),
-	);
-
-	withMtime.sort((a, b) => b.mtimeMs - a.mtimeMs);
-	const latest = withMtime[0];
-	const content = (await safeReadFile(latest.fullPath)).trim();
-	if (!content) return "";
-
-	return `Source: ${latest.name}\n${truncate(content, MAX_HANDOFF_CHARS)}`;
-}
-
-/**
- * Read in-progress beads directly from SQLite database.
- * Cross-platform alternative to shell command execution.
- */
-function readInProgressBeads(directory: string): string {
-	const dbPath = path.join(directory, ".beads", "beads.db");
-	let db: Database | undefined;
-
-	try {
-		db = new Database(dbPath, { readonly: true });
-
-		const rows = db
-			.query<BeadRow, [number]>(
-				"SELECT id, title FROM issues WHERE status = 'in_progress' ORDER BY updated_at DESC LIMIT ?",
-			)
-			.all(MAX_BEADS);
-
-		if (rows.length === 0) return "";
-
-		return rows.map((row) => `- ${row.id}: ${row.title}`).join("\n");
-	} catch {
-		// Database may not exist, be locked, or have different schema
-		// Return empty string to allow graceful degradation
-		return "";
-	} finally {
-		db?.close();
-	}
-}
-
-export const CompactionPlugin: Plugin = async ({ directory }) => {
-	const memoryDir = path.join(directory, ".opencode", "memory");
-	const handoffDir = path.join(memoryDir, "handoffs");
-
-	return {
-		"experimental.session.compacting": async (_input, output) => {
-			const sessionContext = truncate(
-				(await safeReadFile(path.join(memoryDir, "session-context.md"))).trim(),
-				MAX_SESSION_CONTEXT_CHARS,
-			);
-
-			const [projectContext, handoffContext] = await Promise.all([
-				readProjectMemoryContext(memoryDir),
-				readLatestHandoff(handoffDir),
-			]);
-
-			// Synchronous SQLite query - no async/await needed
-			const beadsContext = readInProgressBeads(directory);
-
-			const combined = [
-				renderSection("Session Continuity", sessionContext),
-				renderSection("Active Beads", beadsContext),
-				renderSection("Previous Handoff", handoffContext),
-				renderSection("Project Memory", projectContext),
-			]
-				.filter(Boolean)
-				.join("\n\n");
-
-			if (combined) {
-				output.context.push(
-					`## Session Context\n${truncate(combined, MAX_COMBINED_CONTEXT_CHARS)}\n`,
-				);
-			}
-
-			output.prompt = `${output.prompt}
-
-<compaction_task>
-Summarize conversation state for reliable continuation after compaction.
-</compaction_task>
-
-<compaction_rules>
-- Preserve exact IDs, file paths, and unresolved constraints.
-- Distinguish completed work from current in-progress work.
-- Keep summary concise and execution-focused.
-- If critical context is missing, state uncertainty explicitly.
-</compaction_rules>
-
-<compaction_output>
-Include:
-- What was done
-- What is being worked on now
-- Files currently in play
-- Next actions
-- Persistent user constraints/preferences
-</compaction_output>
-`;
-		},
-	};
-};