opencodekit 0.16.0 → 0.16.1

package/dist/index.js

@@ -750,7 +750,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.16.0",
+  version: "0.16.1",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
   keywords: ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
   license: "MIT",

package/dist/template/.opencode/AGENTS.md

@@ -219,17 +219,51 @@ Chain: grep → read → LSP(9) → memory → understand → edit
 
 **DO NOT proceed without checking memory proactively.** Memory is your external brain. Use it before you start work, not just when someone asks you to.
 
+### Memory Architecture
+
+The memory system uses **SQLite + FTS5** as the single source of truth:
+
+```
+Write: observation() → SQLite only
+       memory-update() → SQLite only
+
+Read:  memory-search() → FTS5 full-text search (BM25 ranking)
+       memory-get() → Full observation details by ID
+       memory-read() → SQLite only
+       memory-timeline() → Chronological context around anchor
+```
+
 ### The Three Actions
 
-First, DO NOT start any significant work without checking memory. Run `memory-search` to find relevant context about the project, the user's preferences, and past decisions. Run `memory-read` for active files that contain information you need to remember. Checking memory before starting prevents you from forgetting important context that affects your work.
+First, DO NOT start any significant work without checking memory. Run `memory-search` to find relevant context using FTS5 full-text search. The search returns a **compact index** (50-100 tokens per result) for progressive disclosure. If you need full details, use `memory-get` with the observation ID.
 
-Second, DO NOT skip saving your own learnings. When you make decisions, discover patterns, or encounter gotchas, use the `observation` tool to save them immediately. Capture the insight before you forget it. What you don't write down, you will lose.
+Second, DO NOT skip saving your own learnings. When you make decisions, discover patterns, or encounter gotchas, use the `observation` tool to save them immediately. Use the enhanced schema:
+
+```typescript
+observation({
+  type: "decision", // decision, bugfix, feature, pattern, discovery, learning, warning
+  title: "Use JWT for auth",
+  narrative: "Why this decision was made...",
+  facts: "stateless, scalable", // Key facts (comma-separated)
+  concepts: "auth, jwt, security", // Keywords for search
+  confidence: "high", // high, medium, low
+});
+```
 
 Third, DO NOT ignore LSP nudges. If the system suggests running an LSP operation and you see that nudge, execute it immediately. Don't defer it and don't skip it. Nudges exist because something needs attention.
 
 ### Memory-start protocol
 
-At the start of any significant task, complete these three steps in order. First, run `memory-search` with relevant keywords to find context. Second, run `memory-read` on project files that might be relevant. Third, run `memory-read` on user preference files to remember what the user wants. Only after completing these steps should you proceed with the actual work.
+At the start of any significant task, complete these three steps in order. First, run `memory-search` with relevant keywords to find context (returns compact index). Second, run `memory-get` for any observations you need full details on. Third, run `memory-read` for handoffs, research, or template files. Only after completing these steps should you proceed with the actual work.
+
+### Progressive Disclosure Pattern
+
+Memory search intentionally returns **compact results** (50-100 tokens each) to avoid context bloat. Follow this pattern:
+
+1. `memory-search({ query: "auth" })` → Get compact index
+2. Identify relevant observation IDs from index
+3. `memory-get({ ids: "42,45" })` → Fetch full details only for what you need
+4. `memory-timeline({ anchor_id: 42 })` → See chronological context if needed
 
 ### Atomic Version
 
@@ -237,8 +271,35 @@ At the start of any significant task, complete these three steps in order. First
 DO NOT start without memory-search.
 DO NOT skip observation on decisions.
 DO NOT ignore LSP Nudges.
+
+Pattern: search → identify IDs → get details → proceed
+```
+
+### Memory Maintenance
+
+For long-term storage health, use `memory-maintain` periodically:
+
+```bash
+# Check current status
+memory-maintain({ operation: "status" })
+
+# Full maintenance (archive >90 days, checkpoint WAL, vacuum)
+memory-maintain({ operation: "full" })
+
+# Preview what would be archived
+memory-maintain({ operation: "archive", older_than_days: 60, dry_run: true })
 ```
 
+**Automatic maintenance** runs at session end:
+
+- FTS5 index optimization
+- WAL checkpoint (if WAL > 1MB)
+
+**Manual maintenance** (run monthly or when storage grows):
+
+- `archive`: Move old observations to archive table
+- `vacuum`: Defragment and reclaim space
+
 ---
 
 ## Beads (Task Tracking)

package/dist/template/.opencode/command/create.md

@@ -22,8 +22,27 @@ Create structured artifacts for a bead using templates. This is the first step b
 ```typescript
 skill({ name: "beads" });
 skill({ name: "brainstorming" });
+skill({ name: "memory-system" });
 ```
 
+## Check Memory First
+
+Search for similar specs and patterns before creating:
+
+```typescript
+// Find similar past specs
+memory_search({ query: "[bead title/description]", limit: 3 });
+
+// Find related patterns and conventions
+memory_search({ query: "[domain keywords] spec requirements", limit: 3 });
+```
+
+Review findings for:
+
+- Similar specs that worked well (reuse structure)
+- Patterns and conventions already established
+- Gotchas to avoid in this domain
+
 ## Load Bead Context
 
 ```bash
@@ -232,6 +251,21 @@ Update bead with note:
 bd note $ARGUMENTS "Created spec.md with [N] requirements"
 ```
 
+## Record Learning (If Significant)
+
+If you discovered patterns or made decisions worth remembering:
+
+```typescript
+observation({
+  type: "pattern", // or "decision"
+  title: "[Domain] spec pattern for [type of feature]",
+  narrative: "When creating specs for [this type], include...",
+  concepts: "[domain keywords]",
+  bead_id: "$ARGUMENTS",
+  confidence: "medium",
+});
+```
+
 ---
 
 ## Output

package/dist/template/.opencode/command/design.md

@@ -11,8 +11,27 @@ subtask: true
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "memory-system" });
 ```
 
+## Check Memory First
+
+Search for existing design decisions and patterns:
+
+```typescript
+// Find similar design work
+memory_search({ query: "[component/page name] design UI", limit: 3 });
+
+// Find design system decisions
+memory_search({ query: "design system colors typography", limit: 3 });
+```
+
+Review findings for:
+
+- Existing aesthetic direction decisions
+- Color and typography choices already made
+- UI patterns that worked well
+
 ## Phase 1: Context Discovery
 
 Parse `$ARGUMENTS` to determine design task:
@@ -565,6 +584,22 @@ Before finalizing, verify design does NOT have ALL of these together:
 **Quick design:** Output inline, no save needed
 **Full design:** Save to `.opencode/memory/design/specs/[YYYY-MM-DD]-[topic].md`
 
+### Record Design Decisions
+
+For significant design choices, create an observation:
+
+```typescript
+observation({
+  type: "decision",
+  title: "Design direction for [component/page]",
+  narrative: "Chose [aesthetic direction] because [rationale]...",
+  facts: "[key design tokens, colors, typography choices]",
+  concepts: "design, ui, [component type], [aesthetic]",
+  bead_id: "$ARGUMENTS", // if applicable
+  confidence: "high",
+});
+```
+
 ### Create Implementation Tasks
 
 For component/page designs:

package/dist/template/.opencode/command/handoff.md

@@ -13,8 +13,23 @@ You're pausing work on a task. Save state so the next session can pick up cleanl
 ```typescript
 skill({ name: "beads" });
 skill({ name: "session-management" });
+skill({ name: "memory-system" });
 ```
 
+## Check Memory for Context
+
+Before creating handoff, search for related work:
+
+```typescript
+// Find previous handoffs and sessions for this bead
+memory_search({ query: "$ARGUMENTS handoff progress", limit: 3 });
+
+// Find related decisions and learnings
+memory_search({ query: "[bead description keywords]", limit: 3 });
+```
+
+Review findings to include relevant context in the handoff.
+
 ## Why Handoff?
 
 - Context window getting full

package/dist/template/.opencode/command/init.md

@@ -1,8 +1,7 @@
 ---
 description: Initialize project for AI-assisted development (creates AGENTS.md + memory files)
 argument-hint: "[--deep] [--skip-questions]"
-agent: plan
-subtask: true
+agent: build
 ---
 
 # Init: $ARGUMENTS
@@ -155,57 +154,49 @@ If the repo is large or keeps changing (monorepos especially), generate/refresh
 
 ## Phase 5: Populate Memory Files
 
-### .opencode/memory/user.md
+Read templates, then use `write` tool to create actual markdown files:
 
-```markdown
----
-purpose: User identity, preferences, communication style
-updated: [today]
----
-
-# User Profile
-
-## Identity
-
-- Name: [from git/questions]
-- Git contributor: [email/username]
-
-## Preferences
-
-- Communication: [terse/detailed]
-- Workflow: [auto-commit/ask-first]
-
-## Rules
-
-[from Phase 1]
+```typescript
+// 1. Read templates to understand structure
+read({ filePath: ".opencode/memory/_templates/user.md" });
+read({ filePath: ".opencode/memory/_templates/tech-stack.md" });
+
+// 2. Use WRITE tool to create/update actual markdown files
+// ⚠️ IMPORTANT: memory-update writes to SQLite, NOT markdown files!
+// Use write() for .md files, memory-update() for SQLite storage
+
+write({
+  filePath: ".opencode/memory/project/user.md",
+  content: "..." // Populated from Phase 1 answers
+});
+
+write({
+  filePath: ".opencode/memory/project/tech-stack.md",
+  content: "..." // Populated from Phase 2 detection
+});
 ```
 
-### .opencode/memory/project/tech-stack.md
-
-```markdown
----
-purpose: Tech stack, constraints, and integrations for AI context injection
-updated: [today]
----
+**Critical distinction:**
+- `write()` → Updates **markdown files** on disk
+- `memory-update()` → Writes to **SQLite database** (memory system)
 
-# Tech Stack
+### .opencode/memory/project/user.md
 
-## Framework & Language
+Populate from Phase 1 answers:
+- Identity (name, git contributor)
+- Communication preferences (terse/detailed)
+- Workflow preferences (auto-commit/ask-first)
+- Custom rules
 
-- **Framework:** [detected, e.g., Next.js 15]
-- **Language:** [detected, e.g., TypeScript]
-- **Runtime:** [detected, e.g., Node.js 22]
-
-## Key Dependencies
-
-- [detected from package.json/go.mod/etc.]
-
-## Key Constraints
+### .opencode/memory/project/tech-stack.md
 
-- [detected or ask user]
-```
+Populate from Phase 2 detection:
+- Framework & version
+- Language & runtime
+- Key dependencies with versions
+- Key constraints
 
-**Note:** AI discovers commands, architecture, conventions, and gotchas organically from the codebase and saves learnings via the `observation` tool. No need for static template files.
+**Note:** AI discovers commands, architecture, conventions, and gotchas organically and saves via `observation` tool.
 
 ## Phase 6: Initialize Beads (if requested)
 
@@ -260,8 +251,10 @@ Suggested next steps:
 ```
 ./AGENTS.md                              # Project-specific rules (created, <60 lines)
 .opencode/AGENTS.md                      # Global rules (untouched)
-.opencode/memory/user.md                 # User preferences (created)
-.opencode/memory/project/tech-stack.md   # Tech stack for context injection (created)
+.opencode/memory/_templates/user.md      # User template
+.opencode/memory/_templates/tech-stack.md # Tech stack template
+.opencode/memory/project/user.md         # User preferences (created from template)
+.opencode/memory/project/tech-stack.md   # Tech stack (created from template)
 .opencode/memory/observations/           # Learnings captured organically by AI
 [packages/*/AGENTS.md]                   # Subsystem rules (--deep, if requested)
 ```

package/dist/template/.opencode/command/plan.md

@@ -24,6 +24,7 @@ skill({ name: "deep-research" });
 skill({ name: "executing-plans" });
 skill({ name: "writing-plans" });
 skill({ name: "subagent-driven-development" });
+skill({ name: "memory-system" });
 ```
 
 ```bash

package/dist/template/.opencode/command/pr.md

@@ -11,8 +11,23 @@ agent: build
 ```typescript
 skill({ name: "beads" }); // Session protocol
 skill({ name: "verification-before-completion" });
+skill({ name: "memory-system" });
 ```
 
+## Check Memory for Related Context
+
+Search for related decisions and patterns:
+
+```typescript
+// Find related decisions and patterns for this work
+memory_search({ query: "$ARGUMENTS [feature keywords]", limit: 3 });
+
+// Find any gotchas related to this area
+memory_search({ query: "[affected files/modules] gotchas", limit: 2 });
+```
+
+Include relevant context from memory in PR description.
+
 ## Options
 
 - `--draft`: Create as draft PR (for WIP or early feedback)

package/dist/template/.opencode/command/research.md

@@ -28,6 +28,9 @@ skill({ name: "source-code-research" });
 
 // For swarm coordination (if parallel research needed)
 skill({ name: "swarm-coordination" });
+
+// For memory context
+skill({ name: "memory-system" });
 ```
 
 ## Delegation Strategy

package/dist/template/.opencode/command/resume.md

@@ -13,6 +13,7 @@ You're picking up where a previous session left off. Recover context, verify sta
 ```typescript
 skill({ name: "beads" });
 skill({ name: "beads-bridge" }); // For cross-session recovery
+skill({ name: "memory-system" });
 ```
 
 ## Verify The Task Exists

package/dist/template/.opencode/command/review-codebase.md

@@ -11,8 +11,23 @@ subtask: true
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "memory-system" });
 ```
 
+## Check Memory for Context
+
+Search for existing patterns and gotchas before review:
+
+```typescript
+// Find related past reviews and findings
+memory_search({ query: "[path/module] review security", limit: 3 });
+
+// Find known gotchas for this area
+memory_search({ query: "[module keywords] gotchas patterns", limit: 3 });
+```
+
+Apply past learnings to the review - don't repeat known issues.
+
 ## Phase 1: Determine Scope
 
 Parse `$ARGUMENTS` to determine what to review:
@@ -205,3 +220,18 @@ Skip creating beads for Minor issues (just report them).
 - Vague feedback ("improve error handling" - WHERE? HOW?)
 - Skipping automated checks "to save time"
 - Not creating beads for real issues (they get forgotten)
+
+## Record Significant Findings
+
+For important findings worth remembering:
+
+```typescript
+observation({
+  type: "warning", // or "pattern", "bugfix"
+  title: "[Module] [Issue type] pattern detected",
+  narrative: "Found [issue] in [location], which can cause...",
+  facts: "[key facts about the issue]",
+  concepts: "[module], security, [issue keywords]",
+  confidence: "high",
+});
+```

package/dist/template/.opencode/command/ship.md

@@ -18,8 +18,23 @@ skill({ name: "finishing-a-development-branch" });
 skill({ name: "receiving-code-review" });
 skill({ name: "swarm-coordination" });
 skill({ name: "beads-bridge" });
+skill({ name: "memory-system" });
 ```
 
+## Check Memory for Context
+
+Search for related patterns and gotchas before shipping:
+
+```typescript
+// Find related patterns and decisions
+memory_search({ query: "$ARGUMENTS [feature keywords]", limit: 3 });
+
+// Find gotchas for affected modules
+memory_search({ query: "[affected modules] gotchas", limit: 3 });
+```
+
+Apply past learnings to avoid known issues.
+
 ## Skill Routing
 
 - Use **systematic-debugging** when a gate fails and root cause is unclear.
@@ -154,3 +169,31 @@ If confirmed:
 bd close $ARGUMENTS --reason "Shipped: verification + review passed"
 bd sync
 ```
+
+## Record Learnings (On Completion)
+
+Before ending, capture what was learned:
+
+```typescript
+// Record significant decisions or patterns discovered
+observation({
+  type: "feature", // or "decision", "pattern"
+  title: "$ARGUMENTS: [brief description]",
+  narrative: "Implemented [feature]. Key approach: [summary]...",
+  facts: "[key implementation details]",
+  concepts: "[domain keywords], [tech stack]",
+  bead_id: "$ARGUMENTS",
+  files_modified: "[key files changed]",
+  confidence: "high",
+});
+
+// If encountered gotchas worth remembering
+observation({
+  type: "warning",
+  title: "[Gotcha discovered during $ARGUMENTS]",
+  narrative: "While implementing, discovered that...",
+  concepts: "[relevant keywords]",
+  bead_id: "$ARGUMENTS",
+  confidence: "high",
+});
+```

package/dist/template/.opencode/command/start.md

@@ -27,6 +27,7 @@ skill({ name: "beads" });
 skill({ name: "beads-bridge" }); // For cross-session todo coordination
 skill({ name: "prd" }); // PRD creation workflow
 skill({ name: "prd-task" }); // PRD to executable tasks conversion
+skill({ name: "memory-system" });
 ```
 
 ## Ensure Git Hooks Installed

package/dist/template/.opencode/command/status.md

@@ -11,9 +11,10 @@ subtask: true
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "memory-system" });
 ```
 
-Generate a comprehensive project status report covering tasks, sessions, git state, and system health.
+Generate a comprehensive project status report covering tasks, sessions, git state, memory health, and system health.
 
 ## Phase 1: Gather All State (Parallel)
 
@@ -250,6 +251,28 @@ Fri ██████████ 10
 
 ## Phase 5: Session Insights
 
+### Memory Health
+
+```typescript
+// Check memory system status
+memory_maintain({ operation: "status", older_than_days: 90, dry_run: false });
+```
+
+Display memory stats in dashboard:
+
+```
+MEMORY STATUS
+━━━━━━━━━━━━
+Observations:     [N] stored
+Database size:    [X] KB
+FTS Index:        ✓ Healthy
+Last search:      [timestamp]
+
+Recent learnings:
+• [Latest observation title] (type: decision)
+• [Latest observation title] (type: pattern)
+```
+
 ### Context Health
 
 ```typescript

package/dist/template/.opencode/command/ui-review.md

@@ -14,6 +14,7 @@ Comprehensive UI/UX review with structured scoring and actionable feedback.
 
 ```typescript
 skill({ name: "beads" }); // Session protocol
+skill({ name: "memory-system" });
 ```
 
 ```typescript
@@ -22,6 +23,20 @@ skill({ name: "visual-analysis" });
 skill({ name: "accessibility-audit" });
 ```
 
+## Check Memory for Design Context
+
+Search for existing design decisions and patterns:
+
+```typescript
+// Find design system decisions
+memory_search({ query: "design system colors typography", limit: 3 });
+
+// Find previous UI reviews and findings
+memory_search({ query: "[component/page] UI review", limit: 3 });
+```
+
+Apply existing design decisions to the review.
+
 ## Parse Arguments
 
 | Argument       | Default  | Description                          |
@@ -305,3 +320,19 @@ bd dep add <task-id> <bead-id>
 | Design from scratch  | `/design`       |
 | Start implementation | `/start <bead>` |
 | Ship implementation  | `/ship <bead>`  |
+
+## Record Significant Findings
+
+For important UI/UX findings worth remembering:
+
+```typescript
+observation({
+  type: "warning", // or "pattern", "decision"
+  title: "UI: [Component/page] [issue type]",
+  narrative: "Found [issue] in [location]. Impact: [description]...",
+  facts: "[severity], [category], [fix approach]",
+  concepts: "ui, accessibility, [component type]",
+  bead_id: "$ARGUMENTS", // if applicable
+  confidence: "high",
+});
+```