opencodekit 0.16.20 → 0.17.0

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

@@ -3,27 +3,103 @@ name: memory-system
 description: Use when persisting learnings, loading previous context, or searching past decisions - covers memory file structure, tools, and when to update each file
 ---
 
-# Memory System
+# Memory System Best Practices
 
-Persistent context that survives across sessions. Uses **SQLite + FTS5** as single source of truth.
+Persistent context that survives across sessions. Uses **SQLite + FTS5** for searchable observations.
 
-## Architecture
+## Core Principle
 
+**Progressive disclosure** — search compactly, fetch fully, timeline chronologically. Never load all memory at once.
+
+---
+
+## The Ritual
+
+Follow this every session. Memory is not optional — it's how knowledge compounds.
+
+### 1. Ground — Search Before You Start
+
+Always search memory first.
+
+```typescript
+// Search for relevant past work
+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 });
 ```
-SQLite Database: .opencode/memory/memory.sqlite
-├── observations table (FTS5 indexed)
-├── handoffs/ subdirectory
-├── research/ subdirectory
-└── project/ subdirectory (commands, conventions, gotchas, architecture)
+
+**Why:** Past you already solved this. Don't rediscover.
+
+### 2. Calibrate — Progressive Disclosure
+
+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" });
+// Returns: [{id: 42, title: "Auth bug fixed", ...}]
+
+// 2. Fetch full details ONLY for relevant IDs
+memory_get({ ids: "42,45" });
+
+// 3. See what led to this decision
+memory_timeline({ anchor_id: 42, depth_before: 3 });
 ```
 
-**Key principle:** All writes go to SQLite. No dual-write pattern. No markdown fallbacks.
+**Why:** Prevents context bloat. High signal, low noise.
+
+### 3. Transform — Record Discoveries
+
+Create observations for anything non-obvious. Don't wait until the end.
+
+```typescript
+observation({
+  type: "pattern", // decision | bugfix | pattern | discovery | warning
+  title: "Brief description",
+  narrative: "Context and reasoning...",
+  facts: "key, facts, here",
+  concepts: "searchable, keywords",
+  files_modified: "src/file.ts",
+});
+```
 
-## Memory Tools
+| Type        | Use When                   | Example                            |
+| ----------- | -------------------------- | ---------------------------------- |
+| `decision`  | Architectural choice made  | "Use zod over yup"                 |
+| `bugfix`    | Root cause found & fixed   | "Race condition in async init"     |
+| `pattern`   | Reusable code pattern      | "Repository with error boundaries" |
+| `discovery` | New capability learned     | "Bun.test supports mocking"        |
+| `warning`   | Dangerous pattern to avoid | "Don't use fs.watch in Docker"     |
+| `learning`  | General insight            | "Always validate at boundary"      |
+
+### 4. Reset — Handoff for Next Session
+
+Document completion state for future you.
+
+```typescript
+memory_update({
+  file: "handoffs/YYYY-MM-DD-task",
+  content: `## Completed
+- X
+
+## Blockers
+- Y
+
+## Next
+- Z`,
+  mode: "append",
+});
+```
+
+---
+
+## Memory Tools Reference
 
 ### memory-search (Start Here)
 
-Fast FTS5 full-text search. Returns **compact index** (50-100 tokens per result) for progressive disclosure.
+Fast FTS5 full-text search. Returns **compact index** for progressive disclosure.
 
 ```typescript
 memory_search({ query: "authentication" });
@@ -41,7 +117,7 @@ memory_search({ query: "patterns", type: "all" }); // Search everything
 
 ### memory-get (Progressive Disclosure)
 
-Fetch full observation details after identifying relevant IDs from search:
+Fetch full observation details after identifying relevant IDs:
 
 ```typescript
 memory_get({ ids: "42" }); // Single observation
@@ -61,7 +137,7 @@ memory_timeline({ anchor_id: 42, depth_before: 5, depth_after: 5 });
 Load project files, handoffs, or templates:
 
 ```typescript
-memory_read({ file: "project/commands" });
+memory_read({ file: "project/gotchas" });
 memory_read({ file: "handoffs/2024-01-20-phase-1" });
 memory_read({ file: "research/auth-patterns" });
 ```
@@ -78,68 +154,67 @@ memory_update({
 });
 ```
 
-## Observations
+---
 
-Record structured findings to SQLite with FTS5 indexing:
+## What Goes Where
 
-```typescript
-observation({
-  type: "decision", // decision, bugfix, feature, pattern, discovery, learning, warning
-  title: "Use JWT auth",
-  narrative: "Decided to use JWT because it's stateless and scales well...",
-  facts: "stateless, scalable, industry standard", // Key facts (comma-separated)
-  concepts: "auth, jwt, security", // Keywords for search
-  confidence: "high", // high, medium, low
-  files_read: "src/auth.ts, src/middleware.ts", // Files consulted
-  files_modified: "src/auth.ts", // Files changed
-  bead_id: "br-abc123", // Link to task (optional)
-});
-```
+### SQLite (observations)
 
-**When to create observations:**
+- Events: decisions, bugfixes, patterns discovered
+- Searchable via FTS5
+- Use `observation()` to create
 
-- Major architectural decisions
-- Bug root causes discovered
-- Patterns worth reusing
-- Gotchas and warnings for future
+### Markdown Files
 
-## Standard Project Files
+- Static knowledge: user preferences, tech stack
+- Handoffs: session summaries
+- Research: deep-dive documents
+- Use `memory_read()` / `memory_update()`
 
-| File                      | Purpose                  | Update When                 |
-| ------------------------- | ------------------------ | --------------------------- |
-| `project/commands.md`     | Build/test/lint commands | Discovering new command     |
-| `project/conventions.md`  | Code patterns, style     | Learning team pattern       |
-| `project/gotchas.md`      | Footguns, warnings       | Hitting unexpected behavior |
-| `project/architecture.md` | Key modules, structure   | Mapping new area            |
+| 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()`                   |
 
-## Progressive Disclosure Pattern
+---
 
-Memory search returns **compact results** to avoid context bloat. Follow this pattern:
+## Observations Schema
 
 ```typescript
-// 1. Search for relevant context
-memory_search({ query: "auth patterns" });
+observation({
+  type: "decision", // decision, bugfix, pattern, discovery, warning, learning
+  title: "Use JWT auth",
+  narrative: "Decided to use JWT because it's stateless...",
+  facts: "stateless, scalable, industry standard",
+  concepts: "auth, jwt, security",
+  confidence: "high", // high, medium, low
+  files_read: "src/auth.ts, src/middleware.ts",
+  files_modified: "src/auth.ts",
+  bead_id: "br-abc123", // Link to task (optional)
+});
+```
 
-// 2. Identify relevant observation IDs from compact index
-// 3. Fetch full details only for what you need
-memory_get({ ids: "42,45" });
+---
 
-// 4. See chronological context if needed
-memory_timeline({ anchor_id: 42 });
-```
+## Anti-Patterns (Don't Do This)
 
-## Best Practices
+| ❌ Don't                            | ✅ Do Instead                          |
+| ----------------------------------- | -------------------------------------- |
+| Load full memory at session start   | Use progressive disclosure             |
+| Create observations for everything  | Only non-obvious decisions             |
+| Duplicate in files AND observations | Files = static, SQLite = events        |
+| Vague search queries                | Use specific keywords, file paths      |
+| Subagents writing to memory         | Only leader agents create observations |
+| Wait until end to record            | Create observations as you discover    |
 
-1. **Search before work** - Run `memory_search` at session start
-2. **Progressive disclosure** - Use search → get → timeline pattern
-3. **Record decisions** - Create observations for non-obvious choices
-4. **Be specific** - Include file paths, function names, concrete examples
-5. **Keep it actionable** - Future agents should know what to do with the info
+---
 
 ## Maintenance
 
-For long-term storage health:
-
 ```typescript
 // Check current status
 memory_admin({ operation: "status" });
@@ -151,12 +226,20 @@ memory_admin({ operation: "full" });
 memory_admin({ operation: "archive", older_than_days: 60, dry_run: true });
 ```
 
-**Automatic maintenance** runs at session end:
+**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.**
 
-- FTS5 index optimization
-- WAL checkpoint (if WAL > 1MB)
+- Search before you build
+- Record what you learned
+- Hand off to future you
 
-**Manual maintenance** (run monthly or when storage grows):
+> "The body is architecture. The breath is wiring. The rhythm is survival."
 
-- `archive`: Move old observations to archive table
-- `vacuum`: Defragment and reclaim space
+Memory is rhythm — it carries knowledge across the silence between sessions.

package/package.json

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