chapterhouse 0.14.0 → 0.14.1

package/dist/memory/manager.js

@@ -55,8 +55,16 @@ export class MemoryManager {
             log.error("git not found on PATH — the memory system requires git; memory is disabled for this run");
             return;
         }
-        await scaffold(this.paths);
-        this.ready = true;
+        try {
+            await scaffold(this.paths);
+            this.ready = true;
+        }
+        catch (err) {
+            // A scaffold failure (missing bundled assets, filesystem error) must not
+            // crash the daemon — disable memory for this run and keep serving.
+            this.disabled = true;
+            log.error({ err }, "memory scaffold failed — memory is disabled for this run");
+        }
     }
     /** The always-loaded hot-tier block, or "" when memory is unavailable. */
     hotTier() {

package/memory-assets/domain-skill.md

@@ -0,0 +1,38 @@
+---
+name: {{ID}}
+description: Use when the conversation involves {{LABEL}}. Triggers — {{TRIGGER_LINE}}. Do not use for topics belonging to other domains.
+---
+
+# {{LABEL}}
+
+Use this skill when the user discusses {{LABEL}} topics.
+
+## Memory Files
+
+Always read on activation:
+- `memory/{{PATH}}/hot-memory.md` (via `cog_read`)
+
+Then load additional files per the memory retrieval protocol based on the query:
+- Status/task query → `memory/{{PATH}}/action-items.md`
+- Entity/people query → `memory/{{PATH}}/entities.md`
+- Update/observation → the target file only
+- Complex query → hot-memory first, then drill into referenced files
+
+Available warm files: {{FILES}}
+
+To find files without opening them, run `cog_l0_scan` scoped to `{{PATH}}`.
+Historical data: `cog_read` on `memory/glacier/index.md`, filter by domain `{{ID}}`.
+
+## Routing
+
+When the user shares information or asks to save something, write with the
+`cog_*` tools:
+- Task/todo → `memory/{{PATH}}/action-items.md`
+- Person/entity → `memory/{{PATH}}/entities.md`
+- Update/log → `memory/{{PATH}}/observations.md`
+- Status/overview → `memory/{{PATH}}/hot-memory.md`
+
+## Activation
+
+Read the hot-memory file, classify the query, load the minimum files needed,
+and respond.

package/memory-assets/seed/cog-meta/improvements.md

@@ -0,0 +1,8 @@
+<!-- L0: Feature ideas, wishlists, and repair notes -->
+# Improvements
+
+<!-- Edit in place by section. -->
+
+## Ideas
+
+## Implemented

package/memory-assets/seed/cog-meta/patterns.md

@@ -0,0 +1,5 @@
+<!-- L0: Distilled interaction and workflow rules from experience -->
+# Learned Patterns
+
+<!-- Edit in place. Distill self-observations into actionable, timeless rules. -->
+<!-- HARD LIMIT: 70 lines / 5.5KB. Domain-specific patterns go in satellite files. -->

package/memory-assets/seed/cog-meta/reflect-cursor.md

@@ -0,0 +1,4 @@
+<!-- L0: Ingestion cursor for the reflect skill over session history -->
+# Reflect Cursor
+
+last_processed: never

package/memory-assets/seed/cog-meta/scenario-calibration.md

@@ -0,0 +1,14 @@
+<!-- L0: Prediction accuracy tracker for decision scenarios -->
+# Scenario Calibration
+
+<!-- Updated by the reflect skill when scenarios resolve. -->
+
+## Resolved Scenarios
+
+| Scenario | Created | Resolved | Predicted Branch | Actual Branch | Accuracy | Lesson |
+|----------|---------|----------|-----------------|---------------|----------|--------|
+
+## Metrics
+
+- Total resolved: 0
+- Accuracy rate: —

package/memory-assets/seed/cog-meta/self-observations.md

@@ -0,0 +1,4 @@
+<!-- L0: What worked and didn't in interactions — append-only -->
+# Self-Observations
+
+<!-- Append-only. Format: - YYYY-MM-DD [tag]: observation -->

package/memory-assets/seed/domains.yml

@@ -0,0 +1,19 @@
+# Chapterhouse Domain Manifest
+# Single source of truth for all memory domains.
+# Add domains with the setup skill, or edit this file directly — Chapterhouse
+# reconciles directories and skill files from it on every startup.
+
+domains:
+  - id: personal
+    path: personal
+    type: personal
+    label: "Family, health, calendar, day-to-day"
+    triggers: [family, health, kids, calendar, personal, home, car, finance]
+    files: [hot-memory, action-items, entities, observations, habits, health, calendar]
+
+  - id: cog-meta
+    path: cog-meta
+    type: system
+    label: "Memory self-knowledge, pipeline health, architecture"
+    triggers: [meta, evolve, pipeline, memory system, architecture]
+    files: [self-observations, patterns, improvements, scenario-calibration, reflect-cursor]

package/memory-assets/seed/glacier/index.md

@@ -0,0 +1,6 @@
+# Glacier Index
+<!-- Auto-generated by the housekeeping skill. Do not edit. -->
+<!-- Last updated: — -->
+
+| File | Domain | Type | Tags | Date Range | Entries | Summary |
+|------|--------|------|------|------------|---------|---------|

package/memory-assets/seed/hot-memory.md

@@ -0,0 +1,5 @@
+<!-- L0: Cross-domain strategic context — identity, active priorities -->
+# Hot Memory
+
+<!-- Rewrite freely. Keep under 50 lines. -->
+<!-- Use the setup skill to populate this with your domains and priorities. -->

package/memory-assets/seed/link-index.md

@@ -0,0 +1,6 @@
+# Memory Link Index
+<!-- Auto-generated by the housekeeping skill. Do not edit. -->
+<!-- Last updated: — -->
+
+| Target | Linked from |
+|--------|-------------|

package/memory-assets/system-instructions.md

@@ -0,0 +1,214 @@
+# Chapterhouse Memory — Operating Instructions
+
+Chapterhouse gives agents persistent memory, self-reflection, and foresight. It is the first layer of continuous awareness — not just recall, but cognition across time.
+
+## Domain Routing & Skills
+
+Domains are defined in `memory/domains.yml`. Each domain skill and pipeline skill self-describes via its skill `description`, so the runtime routes to them automatically. Without a skill active, use judgment: casual conversation → personal domain; questions about a tracked domain → that domain.
+
+## Memory System
+
+Persistent memory lives in `memory/`. Three tiers:
+
+- **Hot** (`*/hot-memory.md`) — loaded every conversation, <50 lines each, rewrite freely
+- **Warm** (domain files) — loaded when skill activates, per-file size limits
+- **Glacier** (`memory/glacier/`) — YAML-frontmattered archives, indexed via `glacier/index.md`
+
+### L0 Headers (Progressive Context Loading)
+
+Every memory file has a one-line L0 summary as **line 1** — a quick answer to "what would I find if I read this file?" (max 80 chars).
+
+**Format:**
+- `<!-- L0: summary here -->` — always the first line of the file, before title or frontmatter
+
+**Maintenance:** When creating or restructuring a memory file, always add/update its L0. Pipeline steps (`housekeeping`, `reflect`) should preserve existing L0 headers and add them to new files.
+
+### L0 → L1 → L2 Retrieval Protocol
+
+Three tiers — L0 is stored, L1 and L2 are retrieval actions:
+
+- **L0** — read the `<!-- L0: ... -->` header. Answer: "is this file relevant?"
+- **L1** — call `cog_l1_outline` to scan section headers (`## ...`, `### ...`). Answer: "which section is relevant?"
+- **L2** — call `cog_read` to read the full file or section.
+
+**Decision rules:**
+1. When uncertain which files are relevant, call `cog_l0_scan` across the domain directory first
+2. If L0 confirms relevance but the file is >80 lines, call `cog_l1_outline` (L1) before full read
+3. For files <80 lines or when you need full context, go directly to L2 via `cog_read`
+4. Hot-memory files are always L2 — they're small by design
+
+### Directory Map
+
+Domains are defined in `memory/domains.yml`. Call `cog_domains` to read the domain manifest.
+
+```
+memory/
+  domains.yml                      # Domain manifest — SSOT for all domains
+  hot-memory.md                    # Cross-domain (read on start)
+  link-index.md                    # Backlink index (generated by housekeeping)
+  cog-meta/                        # Cog self-improvement (read on start)
+    self-observations.md           # What worked/didn't — append-only
+    patterns.md                    # Distilled interaction patterns — edit in place
+    improvements.md                # Ideas, wishlists, repair notes — edit in place
+    scenario-calibration.md        # Scenario accuracy tracking (updated by reflect)
+    reflect-cursor.md              # Ingestion cursor (last_processed) for the reflect skill
+    scenarios/                     # Active decision simulations (one .md per scenario)
+  personal/                        # Default domain: hot-memory, observations, action-items,
+    ...                            # entities, calendar, health, habits
+  work/                            # Work domains go here (add via setup)
+    <your-job>/                    # hot-memory, observations, action-items, entities,
+    <side-project>/                # projects, dev-log (same structure for all)
+  glacier/                         # Archived data by domain
+    index.md                       # Glacier catalog (generated by housekeeping)
+```
+
+### Threads — The Zettelkasten Layer
+
+Threads are **read-optimized synthesis files**. While observations capture raw events (write-optimized), threads pull related fragments into a coherent narrative. One file per topic, consistent spine:
+
+- **Current State** — what's true right now (rewrite freely, always current)
+- **Timeline** — dated entries, append-only, full detail preserved (never condensed)
+- **Insights** — learnings, patterns, what's different this time
+
+**Raising a thread:** "Raise" is the verb for creating or updating a thread. A thread gets raised when a topic appears in 3+ observations across 2+ weeks, or when the user says "raise X" or "thread X". Call `cog_search` to find all references across observations and memory files, synthesize the narrative arc, write or update the thread with the spine structure using `cog_write` or `cog_edit`, and link source fragments via wiki-links.
+
+**Rules:**
+- **One file forever** — threads grow long, they don't split or condense
+- **Texture is the value** — every entry keeps its full detail, quotes, and dates
+- **Fragments never move** — threads reference them, don't replace them
+- **Current State is always current** — rewrite it freely as things change
+
+Thread files live in their domain directory (e.g., `memory/personal/running.md`, `memory/work/acme/npm-token-governance.md`). Housekeeping detects thread candidates: topic appears in 3+ observations across 2+ weeks → suggest raising.
+
+### Session Transcripts
+
+Call `cog_sessions` (it returns recent conversation history; pass the cursor from `memory/cog-meta/reflect-cursor.md`).
+
+The `reflect` skill reads recent session transcripts to review interactions, catch missed cues, and identify memory gaps.
+
+### Memory Rules
+
+1. **Read on start**: Always read `memory/hot-memory.md` and `memory/cog-meta/patterns.md` at conversation start
+2. **Write immediately**: Don't wait to save something worth remembering
+3. **Observations are append-only**: `- YYYY-MM-DD [tags]: <observation>` — never edit past entries
+   - Tags: `health`, `habits`, `family`, `milestone`, `work`, `insight`, `regression`, `philosophy`, `mental-health`
+4. **Action items**: `- [ ] task | due:YYYY-MM-DD | pri:critical/high/med/low | domain:tag | added:YYYY-MM-DD` / `- [x] task (done YYYY-MM-DD)`. Fields after task are optional — use what's relevant. `pri:` defaults to medium if omitted.
+5. **Entities**: 3-line compact registry format. Each entry: `### Name (relationship)` / pipe-separated key facts / `status: active|inactive | last: YYYY-MM-DD | → [[link]]`. Max 3 content lines per entry. Heavy entries promoted to detail thread files — entity stub links to thread via `→ [[link]]`. Cross-domain entities: canonical entry in primary domain, pointer in secondary (e.g. `see [[work/acme/entities#Jane]]` in personal). **Temporal validity**: When a fact changes, mark old value as superseded with date. `last:` dates updated by reflect from journal/session scans. Entities inactive 6+ months → housekeeping moves to glacier.
+6. **Hot memory <50 lines**: Prune aggressively, move detail to observations
+7. **Self-improvement**: After notable interactions, call `cog_append` to append to `cog-meta/self-observations.md`. Periodically distill patterns into `cog-meta/patterns.md` via `cog_edit`
+   - **Pattern routing**: Core patterns (`cog-meta/patterns.md`, ≤70 lines / 5.5KB) are universal rules injected every turn. Domain-specific patterns go in satellite files (e.g. `work/acme/patterns.md`) loaded only by their owning skill. New patterns go to the appropriate satellite if domain-specific, or core if universal. Satellite files have a soft cap of 30 lines each.
+8. **Single Source of Truth (SSOT)**: Each fact lives in ONE canonical file. Other files reference via `[[link]]`, never copy.
+   - `entities.md` — people, organizations, named things
+   - `action-items.md` — all tasks
+   - `health.md` — medical and health facts
+   - `calendar.md` — scheduled events
+   - `hot-memory.md` — current-state summaries (pointers, not source facts)
+   - `observations.md` — raw timestamped events (never edit past entries)
+   When the same fact appears in two files: keep it in the canonical file, replace the duplicate with a `[[link]]`.
+9. **Wiki-links**: Use `[[domain/filename]]` or `[[domain/filename#Section]]` to cross-reference memory files
+   - Path is relative to `memory/`, no `.md` extension (e.g., `[[personal/health]]`, `[[work/acme/entities#Jane]]`)
+   - Follow links when the linked topic is relevant — don't chase every link mechanically
+   - To discover what links TO a file, call `cog_read` on `memory/link-index.md` (generated by housekeeping)
+   - **Write-time linking (primary)**: When writing or editing ANY memory file, actively add `[[links]]` to related files. This is the main way links get created.
+   - **Write-time back-linking**: When you add a link A→B, ask: "does B benefit from pointing back to A?" If yes, open B via `cog_edit` and add `[[A]]` where relevant. Not every link needs a reciprocal — only add B→A when B genuinely gains context.
+   - **Discovery via link-index**: To find what connects to a file you're reading, call `cog_read` on `memory/link-index.md`.
+   - Housekeeping runs a link audit as a safety net
+10. **Progressive condensation**: Two processes:
+   - **Condensation**: `observations.md` (append) → `patterns.md` (distill 3+ on same theme) → `hot-memory.md` (rewrite freely). Each layer is smaller and more actionable.
+   - **Archival**: Old observations (>50) → `glacier/` (indexed, retrievable). Resolved patterns → remove from hot-memory, keep in patterns.
+     During reflect: check if any observation clusters should promote to patterns.
+     During housekeeping: check if any patterns should promote/demote from hot-memory.
+
+### Memory Retrieval Protocol
+
+When responding to any query:
+
+1. **Identify domain** — match query to a domain via file structure knowledge
+2. **L0 scan** — once you know the domain, call `cog_l0_scan` on `memory/{domain}/` to get all file summaries in one call. This replaces reading INDEX.md — faster and fewer tokens. Use this to pick the right file(s) before opening anything.
+3. **Select files by query type:**
+   - Schedule, tasks → action-items.md + calendar.md
+   - Person, "who is" → entities.md
+   - Overview, "how's my" → hot-memory.md + action-items.md
+   - Following a `[[wiki-link]]` → check link-index.md for related files
+4. **Apply L1 before L2 for long files** — for any file >80 lines, call `cog_l1_outline` before calling `cog_read`
+5. **SSOT check on write** — before writing a fact, check if it already exists in its canonical file. Update there, don't duplicate.
+6. Default: if unclear, read hot-memory + action-items for the likely domain
+
+### File Edit Patterns
+
+| File                            | Pattern                                               | Tool |
+| ------------------------------- | ----------------------------------------------------- | ---- |
+| `hot-memory.md`                 | Rewrite freely                                        | `cog_write` |
+| `observations.md`               | Append only                                           | `cog_append` |
+| `action-items.md`               | Append new, check off done                            | `cog_append` / `cog_edit` |
+| `entities.md`                   | 3-line registry: `### Name` / key facts / `status\|last\|→[[link]]`. Max 3 content lines per entry | `cog_edit` |
+| `calendar.md`                   | Edit in place                                         | `cog_edit` |
+| `health.md`                     | Edit `## Current State`, append to `## History`       | `cog_edit` / `cog_append` |
+| `philosophy.md`                 | Edit in place                                         | `cog_edit` |
+| `habits.md`                     | Edit `## Current State`, leave `## Patterns`          | `cog_edit` |
+| `home.md`                       | Edit `## Current`, append done to `## History`        | `cog_edit` / `cog_append` |
+| Thread files                    | Current State: rewrite. Timeline: append only         | `cog_edit` / `cog_append` |
+| `cog-meta/self-observations.md` | Append only                                           | `cog_append` |
+| `cog-meta/patterns.md`          | Edit in place, distill from self-observations         | `cog_edit` |
+| `cog-meta/improvements.md`      | Edit in place by section                              | `cog_edit` |
+| `link-index.md`                 | Auto-generated by housekeeping — do not edit manually | — |
+| `cog-meta/scenario-calibration.md` | Updated by reflect — scenario accuracy tracking    | `cog_edit` |
+| `cog-meta/scenarios/*.md`       | Created by scenario skill, reviewed by reflect        | `cog_write` / `cog_edit` |
+| `cog-meta/briefing-bridge.md`   | Auto-generated by housekeeping — consumed by foresight | — |
+| `cog-meta/foresight-nudge.md`   | Auto-generated by foresight — one nudge per run       | `cog_write` |
+| `glacier/index.md`              | Auto-generated by housekeeping — do not edit manually | — |
+
+### Glacier Archival
+
+When files exceed limits, call `cog_move` to move old data to `memory/glacier/{domain}/`.
+
+**All glacier files get YAML frontmatter** at the top for fast retrieval:
+
+```yaml
+---
+type: observations|projects|action-items-done|dev-log|entities-inactive|annual-review|improvements-done
+domain: <domain-id from domains.yml>
+tags: [relevant, tags] # observations only
+date_range: YYYY-MM to YYYY-MM
+entries: <count>
+summary: <1-line description>
+---
+```
+
+When archiving new entries to an existing glacier file, update the frontmatter: bump `entries`, extend `date_range`, update `tags` list.
+
+**Retrieval flow**:
+
+1. Call `cog_read` on `memory/glacier/index.md` (one small file — the full catalog)
+2. Filter by domain/tags/date_range in the table
+3. Call `cog_read` on only the matching glacier files
+
+#### Observations — archive by primary tag
+
+Group entries by their **primary tag** (first tag in the bracket list). In work domains where every entry starts with `[work, ...]`, use the differentiating tag (e.g., `milestone`, `insight`).
+
+- `observations.md` >50 entries → `glacier/{domain}/observations-{tag}.md`
+- `cog-meta/self-observations.md` >50 entries → `glacier/cog-meta/observations-{tag}.md`
+- When a single tag file exceeds 50 entries, split by year: `observations-{tag}-{YYYY}.md`
+
+#### Other files — keep existing naming
+
+- `projects.md` >10 completed → `projects-completed-{YYYY}.md`
+- `entities.md` >150 lines → inactive 6mo+ to `entities-inactive.md` (leave stub)
+- `action-items.md` >10 completed → `action-items-done.md`
+- `dev-log.md` >20 entries → `dev-log-{YYYY}.md`
+- `health.md` history >15 entries → `health-history.md`
+- `cog-meta/improvements.md` >10 implemented → `glacier/cog-meta/improvements-done-{YYYY}.md`
+
+## Pipeline
+
+Chapterhouse includes pipeline skills that maintain memory health. Run them manually or on a schedule:
+
+| Skill | Purpose | Suggested schedule |
+|-------|---------|-------------------|
+| `housekeeping` | Archive, prune, link audit, glacier index | Weekly or nightly |
+| `reflect` | Mine conversations, condense patterns, detect threads | Weekly or nightly |
+| `evolve` | Audit architecture, propose rule changes | Weekly |
+| `foresight` | Cross-domain strategic nudge | Daily (morning) |
+
+These are optional — Chapterhouse works without them. But running them regularly keeps memory clean and surfaces insights you'd miss.

package/memory-assets/templates/action-items.md

@@ -0,0 +1,8 @@
+# {{LABEL}} — Action Items
+<!-- L0: Open and completed tasks -->
+
+<!-- Format: - [ ] task | due:YYYY-MM-DD | pri:high/medium/low | added:YYYY-MM-DD -->
+
+## Open
+
+## Completed

package/memory-assets/templates/entities.md

@@ -0,0 +1,4 @@
+# {{LABEL}} — Entities
+<!-- L0: People, places, and things -->
+
+<!-- Edit in place by ### Name header. Max 3 content lines per entry. -->

package/memory-assets/templates/generic.md

@@ -0,0 +1,2 @@
+# {{LABEL}} — {{FILE}}
+<!-- L0: {{FILE}} data -->

package/memory-assets/templates/hot-memory.md

@@ -0,0 +1,4 @@
+# {{LABEL}} — Hot Memory
+<!-- L0: Current state and top-of-mind for {{LABEL}} -->
+
+<!-- Rewrite freely. Keep under 50 lines. -->

package/memory-assets/templates/observations.md

@@ -0,0 +1,4 @@
+# {{LABEL}} — Observations
+<!-- L0: Timestamped observations and events -->
+
+<!-- Append-only. Format: - YYYY-MM-DD [tags]: observation -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chapterhouse",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "Chapterhouse — a team-level AI assistant for engineering teams, built on the GitHub Copilot SDK. Web UI only.",
   "bin": {
     "chapterhouse": "dist/cli.js"
@@ -10,6 +10,7 @@
     ".pr-types.json",
     "agents/",
     "skills/",
+    "memory-assets/",
     "web/dist/",
     "README.md",
     "LICENSE"