@stackmemoryai/stackmemory 1.10.4 → 1.12.0

package/packs/core/commands/learn.md

@@ -0,0 +1,73 @@
+# /learn — Review session and identify what to update
+
+Run /summary internally, then audit what scripts, skills, commands, or memories need updating based on this session's work.
+
+## Execution
+
+### Phase 1: Session Review (silent)
+
+Internally run the /summary logic — review conversation history for all actions, decisions, patterns, and corrections. Do NOT output the summary separately.
+
+### Phase 2: Audit (parallel)
+
+Compare session activity against persistent artifacts:
+
+1. **Memory** — Read `MEMORY.md` from project memory dir
+   - Any new patterns, gotchas, or decisions that should be saved?
+   - Any existing memories now stale or contradicted by this session?
+   - Any user corrections/feedback worth persisting?
+
+2. **CLAUDE.md** — Read project and global CLAUDE.md
+   - Any new commands, paths, or conventions discovered?
+   - Any documented patterns that are now wrong?
+
+3. **Skills/Commands** — Glob `~/.claude/commands/*.md` and project `.claude/commands/*.md`
+   - Any skills that broke or need updating?
+   - Any new workflow worth turning into a skill?
+
+4. **Scripts** — Check `scripts/`, `.husky/`, hook files
+   - Any scripts created or modified this session?
+   - Any hooks that failed and need fixing?
+
+5. **Wiki** — If wiki exists, check for stale articles
+   - Any new entities or concepts from this session?
+
+### Phase 3: Report
+
+Output in this format:
+
+```
+## Session Learnings
+
+**What happened:**
+- [1-line per action/outcome]
+
+**Updates needed:**
+
+| Target | Action | Detail |
+|--------|--------|--------|
+| memory/X.md | create/update/delete | [what and why] |
+| CLAUDE.md | update | [section + change] |
+| commands/X.md | create/update | [what] |
+| scripts/X | update | [what] |
+| wiki/X.md | create/update | [what] |
+
+**No action needed:**
+- [artifacts reviewed but current]
+```
+
+### Phase 4: Execute (with confirmation)
+
+Ask: "Apply these updates? (all / pick / skip)"
+
+- **all**: Apply every update in the table
+- **pick**: Let user select which ones
+- **skip**: Report only, no changes
+
+## Rules
+
+- Don't create memories for ephemeral task details — only durable learnings
+- Don't update CLAUDE.md for one-off patterns — only if it'll recur
+- Bias toward updating existing memories over creating new ones
+- Keep the report under 30 lines — dense, not verbose
+- If nothing needs updating, say so in one line and stop

package/packs/core/commands/next.md

@@ -0,0 +1,36 @@
+# /next — What should I do next?
+
+Read context and suggest the highest-impact next action.
+
+## Context to gather (parallel)
+
+1. **Git state**: `git status`, `git branch --show-current`, `git log --oneline -3`
+2. **Open PR for branch**: `/opt/homebrew/bin/gh pr view --json title,state,reviews,checks 2>/dev/null`
+3. **GHA status**: `/opt/homebrew/bin/gh run list --branch $(git branch --show-current) --limit 1 --json status,conclusion,name 2>/dev/null`
+4. **Memory**: Read `MEMORY.md` and `project_todos_queue.md` from the project memory directory
+5. **Uncommitted work**: `git diff --stat HEAD`
+
+## Decision logic
+
+Evaluate in priority order. Pick the FIRST that applies:
+
+1. **Uncommitted changes exist** → suggest commit or continue current work
+2. **PR open + CI failing** → suggest fix CI failures
+3. **PR open + Greptile comments** → suggest `/greptile-fix`
+4. **PR open + CI passing + no reviews** → suggest waiting or starting next task
+5. **On feature branch, no PR** → suggest `/pr`
+6. **On master, clean** → suggest next task from queue (pick highest priority unchecked item)
+
+## Output format
+
+```
+## Next up
+
+[One sentence: what to do and why]
+
+A) [Primary action — the recommendation]
+B) [Alternative action]
+C) [Skip — pick something else from queue]
+```
+
+Always present A/B/C options. Keep it to 5 lines max. No preamble.

package/packs/core/commands/restart.md

@@ -0,0 +1,58 @@
+# /restart — Close session, clear context, and reboot
+
+Chain `/stop done` → `/clear` → `/start` in one command. Use when switching contexts or resetting after a long session.
+
+## Usage
+
+`$ARGUMENTS` — optional: `quick` (skip /learn, just capture + clear + start)
+
+## Execution
+
+### Phase 1: Stop (condensed)
+
+Run /stop logic with `done` mode:
+
+1. **Summary** — Review all actions, decisions, files changed (hold output)
+2. **Capture** — Run `stackmemory capture --no-commit`
+   - If uncommitted changes exist, ask: "Commit before restart? (y/n)"
+   - If yes: commit, re-capture
+3. **Learn** — Unless `quick` argument was passed:
+   - Audit memory, CLAUDE.md, skills for needed updates
+   - Apply non-controversial updates automatically
+   - Ask for confirmation on new memories or CLAUDE.md changes
+4. Output the stop summary (keep under 15 lines):
+
+```
+## Closing session
+
+**Done:** [1-3 bullet summary]
+**Captured:** [yes/no]
+**Updates:** [applied/none]
+```
+
+### Phase 2: Clear
+
+Tell the user: "Clearing context. Starting fresh session..."
+
+Then run `/clear` to reset the conversation context.
+
+### Phase 3: Start
+
+Run full /start logic:
+
+1. **Context Load** (parallel):
+   - Git state: branch, log, status, stash list
+   - Restore: `stackmemory restore --no-copy`
+   - Open PRs: `gh pr list --author @me --state open --limit 5`
+   - Memory: review MEMORY.md
+2. **Situational Awareness** — branch state, handoff, PRs, stashes
+3. **Output** — standard /start format with branch, commits, next steps
+
+## Rules
+
+- If /stop capture fails, warn but continue — don't block the restart
+- Never force-clear with uncommitted work — always ask first
+- If `quick` mode, skip /learn entirely (saves ~30s)
+- The /clear step resets conversation context — everything after is a fresh start
+- Total output: stop summary (15 lines) + start output (25 lines)
+- If any phase fails, continue to the next — report errors inline

package/packs/core/commands/restore.md

@@ -0,0 +1,29 @@
+# /restore — Restore session context via StackMemory
+
+Run `stackmemory restore` to load context from the last handoff and resume where you left off.
+
+## Usage
+
+`$ARGUMENTS` — optional flags passed directly to `stackmemory restore`.
+
+## Behavior
+
+1. Run `stackmemory restore $ARGUMENTS`
+2. Read the restored handoff prompt
+3. Use the restored context to understand current state: branch, in-progress work, blockers, next steps
+4. Run `stackmemory status` to confirm project state
+5. Summarize what was restored and suggest next actions
+
+## Common flags
+
+| Flag | Effect |
+|------|--------|
+| `--no-copy` | Don't copy prompt to clipboard |
+| `--force` | Restore even if branch doesn't match |
+
+## Examples
+
+```
+/restore              # Restore last handoff
+/restore --force      # Restore even on different branch
+```

package/packs/core/commands/start.md

@@ -0,0 +1,57 @@
+# /start — Boot a session with full context
+
+Load memory, restore last handoff, review recent history, and suggest what to work on.
+
+## Execution
+
+Run all phases. Keep output tight — the user wants to start working, not read a report.
+
+### Phase 1: Context Load (parallel)
+
+1. **Memory** — Read `MEMORY.md` from project memory dir (already in context, just review)
+2. **Git state** — Run in parallel:
+   - `git branch --show-current`
+   - `git log --oneline -10`
+   - `git status`
+   - `git stash list`
+3. **Restore** — Run `stackmemory restore --no-copy` to load last handoff
+4. **Open PRs** — `/opt/homebrew/bin/gh pr list --author @me --state open --limit 5 --json number,title,headRefName,reviews,statusCheckRollup 2>/dev/null`
+
+### Phase 2: Situational Awareness
+
+From the gathered context, determine:
+
+- **Current branch** and whether it has uncommitted work
+- **Last session's state** from the handoff (in-progress work, blockers, next steps)
+- **Open PRs** and their CI/review status
+- **Any stashes** that might be forgotten work
+
+### Phase 3: Output
+
+```
+## Session Start
+
+**Branch:** [branch] [clean|dirty]
+**Last session:** [1-line summary from handoff]
+**Open PRs:** [count] — [brief status of each]
+
+**Recent commits:**
+- [last 3-5 relevant commits, 1 line each]
+
+**Restored context:**
+- [key items from handoff: active work, blockers, decisions]
+
+## What's next
+
+A) [Primary — continue from handoff / fix CI / address review]
+B) [Alternative]
+C) [Something else]
+```
+
+## Rules
+
+- Total output under 25 lines
+- Don't re-read files already in context (CLAUDE.md, MEMORY.md)
+- If restore fails (no handoff), skip gracefully — still show git state + suggest /next
+- If on main with clean state and no handoff, just run /next logic directly
+- Never block on a failed command — report and continue

package/packs/core/commands/stop.md

@@ -0,0 +1,65 @@
+# /stop — End a session cleanly
+
+Run /summary → /capture → /learn, then either /compact or clear based on whether work remains.
+
+## Usage
+
+`$ARGUMENTS` — optional: `done` (session complete, clear context) or omit (default: compact for continuation)
+
+## Execution
+
+### Phase 1: Summary (silent)
+
+Run /summary logic internally — review all actions, decisions, files changed. Hold the output for Phase 3.
+
+### Phase 2: Capture
+
+1. Run `stackmemory capture --no-commit` to generate handoff
+2. If there are uncommitted changes, ask: "Commit before closing? (y/n)"
+   - If yes: commit with auto-generated message, then re-run capture
+
+### Phase 3: Learn
+
+Run /learn logic — audit memory, CLAUDE.md, skills, scripts for needed updates.
+
+Output the combined summary + learnings report:
+
+```
+## Session Close
+
+**What was done:**
+- [actions from summary]
+
+**Captured:** [handoff saved / failed]
+
+**Updates needed:**
+| Target | Action | Detail |
+|--------|--------|--------|
+| ... | ... | ... |
+
+**Updates applied:** [list] or "none needed"
+```
+
+Apply any non-controversial updates automatically (stale memory cleanup, factual corrections). Ask for confirmation on new memories or CLAUDE.md changes.
+
+### Phase 4: Close
+
+Determine session state:
+
+**If `done` argument OR no open work remaining:**
+- All tasks complete, no blockers, clean branch
+- Output: "Session complete. Clearing context."
+- Clear conversation (suggest user run /clear)
+
+**If work remains (default):**
+- Open tasks, uncommitted changes, or active blockers
+- Run /compact to preserve context for continuation
+- Output: "Compacted. Resume with /start"
+
+## Rules
+
+- Total output under 30 lines (excluding the updates table)
+- If /learn finds nothing to update, skip the table — just say "Nothing to update"
+- If capture fails, warn but continue — don't block the close
+- Commit confirmation only if there are actual uncommitted changes
+- Never force-clear if there's uncommitted work — always warn first

package/packs/core/commands/summary.md

@@ -0,0 +1,40 @@
+# /summary — Summarize what was accomplished this session
+
+Generate a concise summary of work done in the current conversation.
+
+## Execution
+
+1. Review the conversation history for all actions taken
+2. Group by topic/theme if multiple things were done
+3. Output in this format:
+
+## Format
+
+```
+## Session Summary
+
+**What was done:**
+- [action 1]
+- [action 2]
+- ...
+
+**Files changed:**
+- [file path] — [what changed]
+
+**Decisions made:**
+- [decision and rationale]
+
+**Status:** [complete | in-progress | blocked]
+
+**Next steps:**
+- [follow-up if any]
+```
+
+## Rules
+
+- Keep it short — one line per item
+- Focus on outcomes, not process
+- Include file paths for any created/modified files
+- Note any new commands, tools, or integrations set up
+- If commits were made, list them
+- Skip filler — no "I helped the user..." framing

package/packs/core/manifest.json

@@ -0,0 +1,24 @@
+{
+  "name": "core",
+  "version": "1.0.0",
+  "description": "Session lifecycle commands for Claude Code — start, stop, restart, and next",
+  "requires": "stackmemory >= 1.10.0",
+  "commands": {
+    "public": [
+      { "file": "commands/start.md", "name": "start", "description": "Boot a session with full context" },
+      { "file": "commands/stop.md", "name": "stop", "description": "End a session cleanly" },
+      { "file": "commands/restart.md", "name": "restart", "description": "Close session, clear context, and reboot" },
+      { "file": "commands/next.md", "name": "next", "description": "What should I do next?" }
+    ],
+    "internal": [
+      { "file": "commands/summary.md", "name": "summary", "description": "Summarize session work (used by /stop)" },
+      { "file": "commands/capture.md", "name": "capture", "description": "Save context via StackMemory (used by /stop)" },
+      { "file": "commands/learn.md", "name": "learn", "description": "Review session and update memory (used by /stop)" },
+      { "file": "commands/restore.md", "name": "restore", "description": "Restore from last handoff (used by /start)" }
+    ]
+  },
+  "install": {
+    "target": "~/.claude/commands",
+    "method": "symlink"
+  }
+}

package/packs/ops/decision-recovery/instructions.md

@@ -0,0 +1,65 @@
+# ops/decision-recovery
+
+## Purpose
+
+Track decisions, recover context, and hand off work between sessions. This pack ensures nothing is lost when an agent session ends, a human picks up work, or context needs to be recovered after a failure.
+
+## Decision Tracking
+
+Every significant decision should be logged with:
+
+1. **The decision itself** — what was chosen
+2. **Rationale** — why (the most important part)
+3. **Alternatives considered** — what else was evaluated
+4. **Confidence level** — how certain (0-1 scale)
+
+### When to log decisions
+
+- Architecture choices (database, framework, protocol)
+- Trade-off resolutions (speed vs. correctness, scope vs. timeline)
+- Integration selections (which tool, which API)
+- Rejection decisions (what was explicitly *not* done, and why)
+- Policy choices (error handling strategy, naming conventions)
+
+### Decision supersession
+
+When a decision is reversed or updated, log the new decision with a reference to the old one. Don't delete old decisions — they provide valuable context about what was tried and why it didn't work.
+
+## Context Recovery
+
+When starting a new session or recovering from a failure:
+
+1. **Check the last handoff** — what was the previous session working on?
+2. **Review recent decisions** — what constraints are in place?
+3. **Check for blockers** — what's preventing progress?
+4. **Review git state** — uncommitted work, open PRs, branch state
+
+### Recovery priority order
+
+1. Uncommitted changes → commit or stash
+2. Open blockers → address or escalate
+3. Failed CI → fix before continuing
+4. In-progress work → resume from handoff
+5. Next task → pick from queue
+
+## Session Handoff
+
+At the end of every session, create a structured handoff:
+
+- **Summary** — 1-3 sentences on what was accomplished
+- **Key decisions** — decisions made during the session
+- **Blockers** — anything that's preventing progress
+- **Next steps** — concrete, actionable items for the next session
+- **Open questions** — things that need human input
+
+### Handoff format
+
+Keep handoffs concise. The next agent or human should be able to resume in < 2 minutes by reading the handoff.
+
+## Anti-Patterns
+
+- Starting work without checking the last handoff → duplicate work
+- Making decisions without logging rationale → lost context
+- Ending a session without a handoff → cold start next time
+- Logging implementation details as decisions → noise
+- Deleting or overwriting old decisions → lost history

package/packs/ops/decision-recovery/pack.yaml

@@ -0,0 +1,89 @@
+name: ops/decision-recovery
+version: 1.0.0
+description: Decision tracking, context recovery, and session handoff patterns for agent workflows
+author: stackmemory
+license: MIT
+runtime:
+  type: local
+ingestion:
+  sources:
+    - linear
+    - github
+  scope: decisions-and-anchors
+ontology:
+  entities:
+    - decision
+    - anchor
+    - blocker
+    - handoff
+    - session
+  relations:
+    - supersedes
+    - blocks
+    - resolves
+    - continues
+mcp:
+  tools:
+    - name: log_decision
+      description: Record a decision with rationale, alternatives considered, and confidence level
+      inputSchema:
+        type: object
+        properties:
+          decision:
+            type: string
+            description: The decision made
+          rationale:
+            type: string
+            description: Why this was chosen
+          alternatives:
+            type: array
+            items:
+              type: string
+            description: Alternatives that were considered
+          confidence:
+            type: number
+            description: Confidence level (0-1)
+        required:
+          - decision
+          - rationale
+    - name: recover_context
+      description: Retrieve decisions, anchors, and blockers from the current or recent sessions
+      inputSchema:
+        type: object
+        properties:
+          scope:
+            type: string
+            enum:
+              - current
+              - recent
+              - all
+            description: How far back to look
+          filter:
+            type: string
+            description: Optional keyword filter
+    - name: create_handoff
+      description: Create a structured session handoff for the next agent or human
+      inputSchema:
+        type: object
+        properties:
+          summary:
+            type: string
+            description: What was accomplished
+          blockers:
+            type: array
+            items:
+              type: string
+            description: Open blockers
+          next_steps:
+            type: array
+            items:
+              type: string
+            description: Suggested next actions
+        required:
+          - summary
+examples:
+  - input: "We decided to use SQLite instead of Postgres for the local store"
+    output: "log_decision({ decision: 'Use SQLite for local store', rationale: 'Zero-config, file-based, FTS5 built-in, no server process', alternatives: ['Postgres', 'Dolt'], confidence: 0.9 })"
+  - input: "What decisions were made in the last session?"
+    output: "recover_context({ scope: 'recent', filter: 'decision' })"
+instructions: instructions.md

package/templates/claude-hooks/doc-ingest.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+/**
+ * Doc Ingest Hook
+ *
+ * Fires on PostToolUse when WebFetch is used. If the fetched URL looks like
+ * documentation (docs.*, /api/, /reference/, /guide/), auto-ingests it into
+ * the project wiki via stackmemory wiki ingest.
+ *
+ * Lightweight: only runs if .stackmemory/config.yaml has obsidian.vaultPath.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Doc URL patterns
+const DOC_PATTERNS = [
+  /^https?:\/\/docs\./i,
+  /^https?:\/\/[^/]+\/docs\//i,
+  /^https?:\/\/[^/]+\/api\//i,
+  /^https?:\/\/[^/]+\/reference\//i,
+  /^https?:\/\/[^/]+\/guide/i,
+  /^https?:\/\/[^/]+\/tutorial/i,
+  /^https?:\/\/developer\./i,
+];
+
+// Rate limit: max 1 ingest per URL per session
+const seen = new Set();
+
+function main() {
+  try {
+    // Only fire on WebFetch tool
+    const toolName = process.env.TOOL_NAME || '';
+    if (toolName !== 'WebFetch') return;
+
+    // Check wiki is configured
+    const configPath = path.join(process.cwd(), '.stackmemory', 'config.yaml');
+    if (!fs.existsSync(configPath)) return;
+    const config = fs.readFileSync(configPath, 'utf-8');
+    if (!config.includes('vaultPath:')) return;
+
+    // Extract URL from tool input
+    const input = process.env.TOOL_INPUT || '';
+    let url;
+    try {
+      const parsed = JSON.parse(input);
+      url = parsed.url;
+    } catch {
+      // Try regex fallback
+      const match = input.match(/https?:\/\/[^\s"']+/);
+      url = match ? match[0] : null;
+    }
+
+    if (!url) return;
+
+    // Check if URL matches doc patterns
+    const isDoc = DOC_PATTERNS.some((p) => p.test(url));
+    if (!isDoc) return;
+
+    // Dedupe per session
+    const host = new URL(url).hostname;
+    if (seen.has(host)) return;
+    seen.add(host);
+
+    // Run ingest (fire-and-forget, max 1 page for auto-ingest)
+    execSync(`stackmemory wiki ingest "${url}" -n 5`, {
+      timeout: 15000,
+      stdio: 'ignore',
+    });
+  } catch {
+    // Silent fail
+  }
+}
+
+main();