@kurrent/kcap 0.8.18 → 0.9.1

package/kcap/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "kcap",
-  "version": "0.8.18",
+  "version": "0.9.1",
   "description": "Records and visualizes Claude Code sessions via kcap CLI hooks"
 }

package/kcap/.codex-mcp.json

@@ -7,6 +7,10 @@
     "kcap-sessions": {
       "command": "kcap",
       "args": ["mcp", "sessions"]
+    },
+    "kcap-memory": {
+      "command": "kcap",
+      "args": ["mcp", "memory"]
     }
   }
 }

package/kcap/.mcp.json

@@ -14,7 +14,13 @@
       "command": "kcap",
       "args": ["mcp", "flows"],
       "cwd": "${CLAUDE_PROJECT_DIR}",
-      "description": "Structured AI review flows — start_review_flow, submit_review_round, get_review_flow_status, close_review_flow. Launches a SEPARATE hosted reviewer agent through your daemon and iterates to sign-off; requires `kcap login` and a running daemon with this repo checked out (the tools are inert otherwise). Use only when the user explicitly asks for a review flow / to submit for review — for an ordinary 'review my PR' or 'code review' request, review directly and do not call these tools."
+      "description": "Structured AI agent flows — start_review_flow, submit_review_round, get_review_flow_status, close_review_flow (review-specific) plus their generic equivalents start_flow, send_to_participant, get_flow_status, close_flow (any flow-definition catalog id). Launches a SEPARATE hosted participant agent through your daemon and iterates to sign-off; requires `kcap login` and a running daemon with this repo checked out (the tools are inert otherwise). Use only when the user explicitly asks for a review flow / agent flow / to submit for review — for an ordinary 'review my PR' or 'code review' request, review directly and do not call these tools."
+    },
+    "kcap-memory": {
+      "command": "kcap",
+      "args": ["mcp", "memory"],
+      "cwd": "${CLAUDE_PROJECT_DIR}",
+      "description": "Team memory — search, read, and save durable learnings scoped to you, your team, or the org."
     }
   }
 }

package/kcap/README.md

@@ -31,6 +31,21 @@ PR review context tools. Each PR-scoped tool accepts an optional `pr` argument (
 | `list_sessions` | Sessions that contributed to the PR | optional |
 | `get_transcript` | Full transcript of a specific session | n/a (keys off `session_id`) |
 
+### `kcap-memory`
+
+Search, save, and update durable team memories — preferences, feedback, project facts, and references scoped to you, your team, or the org.
+
+| Tool | Description |
+|------|-------------|
+| `search_memories` | Hybrid semantic + keyword search over memories visible to you |
+| `get_memory` | Fetch a memory's full content by id or slug |
+| `save_memory` | Save a new memory (`audience`, `slug`, `description`, `content`, `kind`); scoped to the cwd repo unless `global: true` |
+| `update_memory` | Update an existing memory's description/content/kind |
+| `rescope_memory` | Change a memory's audience (e.g. promote user → team/org) |
+| `archive_memory` | Soft-delete a memory |
+
+Repo- and machine-aware: it resolves the cwd to a repo hash and the local persisted machine id at startup to scope saves and bias search results.
+
 `kcap mcp judge` is intentionally not auto-registered. Add it with `claude mcp add kcap-judge -- kcap mcp judge` if you want it.
 
 **Hooks** — Automatically captures session activity and forwards it to the Kurrent Capacitor server:

package/kcap/skills/agent-flows/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: agent-flows
+description: >-
+  This skill should be used ONLY when the user explicitly asks to run a
+  structured agent *flow* by name or definition id — e.g. "start a flow",
+  "run the code-review flow", "run the X flow", "use flow definition X",
+  "kick off an agent flow", or wants an iterative loop run by a separate
+  hosted participant agent that continues until sign-off. It covers the same
+  underlying tools as the `review-flows` skill (`start_review_flow` etc. are
+  aliases of the generic tools documented here) — use `review-flows` for the
+  two built-in review kinds (`spec-review`, `code-review`) and this skill for
+  any other flow definition, or when the user names a `definition_id`
+  explicitly. Do NOT use this skill (and do NOT call the flows MCP tools) for
+  an ordinary request such as "review my PR", "do X for me", or "check this
+  over" where the user just wants you to do the work yourself — perform that
+  work directly instead.
+---
+
+# Agent Flows
+
+Use the `kcap mcp flows` MCP tools (`start_flow`, `send_to_participant`, `get_flow_status`, `close_flow`) to run a structured agent **flow**: your work is handed to a **separate, hosted participant agent** driven by a flow definition from the server's catalog, which returns a result per that definition's markers (e.g. `FINDINGS:` / `NO FINDINGS` for the review-style built-ins); you address the result and keep iterating until the definition's clean/complete signal. This is a deliberate, heavier workflow — use it only when the user explicitly opts into it.
+
+## When NOT to use this skill / these tools
+
+These tools do **not** perform the work themselves — they hand it off to a separate hosted participant agent running a named flow definition. If the user simply asked *you* to do something in a normal session — e.g. "review my PR", "review this diff", "check this spec", "do X" — just do it yourself and report the result directly. Do **NOT** call `start_flow` / `send_to_participant` for an ordinary request; that would spin up a hosted agent the user did not ask for.
+
+Only start a flow when the user explicitly asks for a flow — e.g. "start a flow", "run the code-review flow", "use flow definition X", or "re-review after I address the findings" via a flow.
+
+## Choosing the flow definition
+
+Once the user has explicitly opted into a flow (see above), pick the `definition_id`:
+
+- Spec or design document → `definition_id: "spec-review"` (built-in; same as `review-flows`' `spec-review` kind)
+- Code changes or a pull request → `definition_id: "code-review"` (built-in; same as `review-flows`' `code-review` kind)
+- Anything else → the definition id the user named, or one you look up in the server's flow-definition catalog at `/admin/flows`. If you're unsure which definition applies, ask the user rather than guessing.
+
+## If the flows MCP tools are not loaded
+
+If `start_flow` / `send_to_participant` are not among the tools available in this session, do NOT try to obtain them:
+
+- Do NOT run `kcap mcp flows` from a shell, do NOT handshake it over stdio/JSON-RPC, and do NOT edit any MCP configuration.
+- The absence is deliberate: hosted flow participants run with all MCP servers stripped, so a participant cannot start a nested flow.
+- If you were asked to do work and these tools are absent, you are most likely the hosted participant inside an existing flow. This skill does not apply to you — skip the workflow below entirely. Perform the requested work directly and end your final message with the definition's result markers (for the review-style built-ins, that's a final message starting with `FINDINGS:` followed by your findings, or `NO FINDINGS`; check any instructions you were given for a custom definition's actual markers). Your final message is captured automatically; no tool call is needed to deliver it.
+
+## Core rules
+
+1. **Start exactly one flow per user task.** Call `start_flow` once and hold the returned `flow_run_id`. Do NOT start a new flow for follow-up rounds — reuse the same ID.
+2. **After receiving a non-clean result**, address it, then call `send_to_participant` with the same `flow_run_id` and the updated message.
+3. **Do NOT finish the user task while the flow has unresolved results.** Keep iterating until the definition's clean/complete signal.
+4. **Only call `close_flow` after the clean signal.** The run stays open until you explicitly close it — don't rely on it closing itself. Then report completion to the user.
+5. **If participant output is unclear or requires user input**, pause and ask the user before proceeding.
+6. **Never start a nested flow.** If you are the hosted participant (see above), do not call these tools yourself.
+7. **Single participant.** In Phase D every flow definition has exactly one participant, `reviewer`. `send_to_participant` with any other `participant` value is rejected by the server, which names the valid participant in its error.
+8. **For a code review flow (`definition_id: "code-review"`), do NOT ask the participant to run tests.** CI covers test execution; participant feedback is on correctness, design, and adherence to conventions.
+
+## Guardrail errors
+
+The server enforces per-run budgets; watch for these in tool error responses:
+
+- **`400` containing `max_rounds (N) reached for this run — close the flow.`** — the run is still **open**, it's just hit its round cap. Stop submitting further rounds, summarize what you have, and call `close_flow`.
+- **`400` containing `budget_exceeded: …`** — the run has **already failed** and the participant agent has stopped. Report this to the user; do NOT retry and do NOT call `close_flow` — closing a failed run overwrites the failure status in the read model (the projector flips `failed` → `closed`), hiding what went wrong.
+- **A round that exceeds the definition's `round_timeout`** lands as a terminal **`unclear`** round, with the timeout explained in its result text — if you check round status programmatically, look for `unclear` and read the text for the timeout reason. The run itself stays open — you may submit another round or close the flow.
+- **Idle runs are auto-reaped** after the definition's `idle_ttl` (server default 24h). Don't rely on this — always call `close_flow` yourself once you're done, whether the outcome was clean or you're abandoning the task.
+
+## Workflow
+
+```
+start_flow(definition_id, target_kind, target_ref, target_title, context)
+  → participant returns a result per the definition's markers (e.g. FINDINGS: … | NO FINDINGS)
+
+if clean (e.g. NO FINDINGS):
+  close_flow(flow_run_id)
+  report completion to user
+  DONE
+
+if not clean (e.g. FINDINGS:):
+  address the result
+  send_to_participant(flow_run_id, participant="reviewer", message=…)
+    → repeat until clean
+  close_flow(flow_run_id)
+  report completion to user
+```
+
+## Tool reference
+
+| Tool | Required args | Optional args | When to call |
+|---|---|---|---|
+| `start_flow` | `definition_id` (e.g. `spec-review`, `code-review`, or a custom catalog id), `target_kind` (what is being worked on: `spec`, `code`, `pr`, `branch`, `file`, etc.), `target_ref` (a path, branch name, or PR URL/number that identifies the target), `target_title` (short human-readable title), `context` (background context: what to focus on, constraints, definition of done) | `instructions`, `mode` (`context-only` — optional; by default, on the same machine, the participant's worktree is mirrored from your working tree including uncommitted changes, so it reads the actual source. Pass `context-only` to opt out and treat the submitted context as authoritative) | Once, at the start of a flow task. |
+| `send_to_participant` | `flow_run_id`, `participant` (Phase D flows have a single participant: `reviewer`), `message` | `instructions`, `async` (defaults to `true`) | After addressing a non-clean result. Pass the same `flow_run_id` and the updated message. |
+| `get_flow_status` | `flow_run_id` | — | Poll or check the current status of a flow run (running, waiting, completed, failed). |
+| `close_flow` | `flow_run_id` | — | Only after the definition's clean signal — or when abandoning the task early; the run otherwise stays open until closed. |
+
+## Example (custom definition)
+
+```
+# Step 1 — start (all five required args must be provided; on the same machine the participant sees
+# your working tree, uncommitted changes included — pass mode="context-only" to opt out)
+start_flow(
+  definition_id="code-review",
+  target_kind="branch",
+  target_ref="feature/add-null-check",
+  target_title="Add null check on user input",
+  context="Review the diff on this branch for correctness and adherence to project conventions."
+)
+# → returns flow_run_id, e.g. "flow_abc123"
+# → participant returns FINDINGS: missing null check on line 42
+
+# Step 2 — address findings, then send a follow-up to the reviewer participant
+send_to_participant(
+  flow_run_id="flow_abc123",
+  participant="reviewer",
+  message="Fixed null check on line 42. Updated diff attached."
+)
+
+# Step 3 — participant returns NO FINDINGS
+close_flow(flow_run_id="flow_abc123")
+# Report to user: flow complete, all findings resolved
+```

package/kcap/skills/recap/SKILL.md

@@ -15,7 +15,7 @@ description: >-
   kcap-sessions MCP tools.
 ---
 
-> **For agents:** When the `kcap-sessions` MCP server is available, prefer its tools (`search_sessions`, `get_session_summary`, `get_session_transcript`) for retrieving past sessions. This CLI-wrapped skill remains a fallback for shell use and when MCP isn't installed.
+> **For agents:** When the `kcap-sessions` MCP server is available, prefer its tools (`search_sessions`, `get_session_summary`, `list_turns`, `get_turn`, `get_session_transcript`) for retrieving past sessions. This CLI-wrapped skill remains a fallback for shell use and when MCP isn't installed.
 
 # Session Recap
 
@@ -26,7 +26,7 @@ Retrieve session history recorded by Kurrent Capacitor. Supports single-session
 **IMPORTANT:** Always use the `kcap recap` CLI command. Do NOT call the HTTP API directly via `curl`, `WebFetch`, or `HttpClient` — the CLI handles formatting, error handling, and server URL resolution.
 
 ```bash
-# Current session summary (default — concise AI-generated overview)
+# Current session summary + per-turn outline (default)
 kcap recap
 
 # Full transcript (all prompts, responses, file changes)
@@ -41,10 +41,17 @@ kcap recap --chain --full
 # Recent session summaries for the current repository
 kcap recap --repo
 
+# Compact per-turn metadata index (no prose)
+kcap recap --per-turn
+
+# One turn's full transcript, drilling down from the outline
+kcap recap --get-turn <N>
+
 # Explicit session ID (overrides env var)
 kcap recap <sessionId>
 kcap recap --full <sessionId>
 kcap recap --chain <sessionId>
+kcap recap --get-turn <N> <sessionId>
 ```
 
 `kcap recap` resolves the current session id from the environment when the host agent CLI exposes one. If no session id is available, pass it explicitly: `kcap recap <sessionId>`.
@@ -61,14 +68,35 @@ Returns AI-generated summaries from the most recent ended sessions in the curren
 
 **Progressive disclosure:** Start with `--repo` for the overview. If a specific session's summary is relevant, drill into it with `kcap recap --full <sessionId>` to get the complete transcript. This avoids loading full transcripts for all sessions into context.
 
-## Default Output (Summary)
+## Default Output
+
+`kcap recap` (no flags) prints, in order:
+
+1. **`## Plan`** — the plan captured for the session, if any.
+2. **`## Summary`** — an AI-generated narrative covering:
+   - **Context** — why the work was done
+   - **Key decisions** — trade-offs and design choices that matter for future work
+   - **Unfinished/Risks** — anything deferred or left incomplete
+3. **`## Turns`** — an outline with one line per turn:
+   - If the turn has a prose summary, that summary (1-3 sentences).
+   - Otherwise, a truncated user-prompt excerpt plus tool/file metadata (tool names, file count).
+4. A closing pointer: `→ kcap recap --get-turn <N> [sessionId]` for one turn's full detail.
+
+A session that has turns but no summary yet (generation hasn't run, or an ended session has no `whats_done`/`plan` entry) still shows the `## Turns` outline — only the plan/summary blocks are skipped. If there's neither a summary nor any turns (e.g. an active session with no recorded turns), recap prints a hint to use `--full` instead.
+
+With `--chain`, this same summary + outline is rendered per session under a `# Session <id>` header, oldest first.
+
+## Turn-by-turn drill-down
+
+Once you've read the `## Turns` outline, fetch one turn's complete transcript (user prompt, tool calls + results, assistant text):
+
+```bash
+kcap recap --get-turn <N> [sessionId]
+```
 
-Shows the plan (if any) and an AI-generated summary with:
-- **Context** — why the work was done
-- **Key decisions** — trade-offs and design choices that matter for future work
-- **Unfinished/Risks** — anything deferred or left incomplete
+For a plain metadata index instead of the outline (turn #, prompt excerpt, tool names, file count, token count, time range — no prose), use `kcap recap --per-turn [sessionId]`.
 
-If no summary is available (e.g., active session), a hint is shown to use `--full`.
+**MCP agents:** call `list_turns` to get a session's full turn map (`turn_index`, `prose`, `user_prompt`, `tools`, `files`, token counts), then `get_turn(session_id, turn_index)` for one turn's full transcript. Use `get_session_summary` for the whole-session narrative instead of drilling into individual turns.
 
 ## Full Output (`--full`)
 
@@ -85,8 +113,10 @@ When using `--chain`, sessions are separated by `# Session <id>` headers, and ag
 ## When to Use Each Flag
 
 - **`--repo`** (`kcap recap --repo`) — recent session summaries across the repo (start here for "what did we do recently?")
-- **No flags** (`kcap recap`) — quick context on the current session
-- **`--full`** (`kcap recap --full`) — when you need exact prompts, responses, or file contents from a specific session
+- **No flags** (`kcap recap`) — summary + per-turn outline for the current session
+- **`--per-turn`** (`kcap recap --per-turn`) — compact metadata index per turn (prompt excerpt, tools, files, tokens, time), no prose
+- **`--get-turn <N>`** (`kcap recap --get-turn <N>`) — one turn's full transcript, drilling down from the outline or the per-turn index
+- **`--full`** (`kcap recap --full`) — whole transcript: exact prompts, responses, and file contents for a specific session
 - **`--chain`** (`kcap recap --chain`) — understanding the full history of a task that spanned multiple sessions
 - **`--chain --full`** — complete transcript across all continuations
 
@@ -97,7 +127,7 @@ The `KCAP_URL` environment variable overrides the default server URL (`http://lo
 ## Tips
 
 - **For "what have we been working on?"** — use `--repo` first, then drill into specific sessions.
-- Start with the default summary. Only use `--full` when you need specific details.
+- Start with the default summary + turn outline. Drill into a specific turn with `--get-turn <N>` before reaching for `--full`.
 - When continuing work from a previous session, use `--chain` to get summaries across continuations.
 - Summarize key decisions and changes for the user rather than echoing the full recap output verbatim.
 - The `kcap` CLI must be available on PATH (typically installed at `~/.local/bin/kcap`).

package/kcap/skills/review-flows/SKILL.md

@@ -15,6 +15,8 @@ description: >-
 
 Use the `kcap mcp flows` MCP tools (`start_review_flow`, `submit_review_round`, …) to run a structured review **flow**: your work is submitted to a **separate, hosted reviewer** agent, which returns findings; you address them and keep iterating until the reviewer returns `NO FINDINGS`. This is a deliberate, heavier workflow — use it only when the user explicitly opts into it.
 
+These four tools are aliases of the generic flow tools (`start_flow`, `send_to_participant`, `get_flow_status`, `close_flow`) — see the `agent-flows` skill for non-review flows.
+
 ## When NOT to use this skill / these tools
 
 These tools do **not** perform a review — they hand the work off to a separate hosted reviewer. If the user simply asked *you* to review something in a normal session — e.g. "review my PR", "review this diff", "code review this", "look over this spec" — just perform the review yourself and report your findings directly. Do **NOT** call `start_review_flow` / `submit_review_round` for an ordinary review request; that would spin up a hosted reviewer the user did not ask for.
@@ -68,7 +70,7 @@ if FINDINGS:
 
 | Tool | Required args | Optional args | When to call |
 |---|---|---|---|
-| `start_review_flow` | `kind` (`spec-review`\|`code-review`), `target_kind` (what is being reviewed: `spec`, `code`, `pr`, `branch`, `file`, etc.), `target_ref` (a path, branch name, or PR URL/number that identifies the target), `target_title` (short human-readable title, e.g. spec name or PR title), `context` (background context: what to focus on, constraints, definition of done) | `instructions`, `mode` (`context-only` — required for code-review unless the reviewer runs in your exact repo checkout) | Once, at the start of a review task. |
+| `start_review_flow` | `kind` (`spec-review`\|`code-review`), `target_kind` (what is being reviewed: `spec`, `code`, `pr`, `branch`, `file`, etc.), `target_ref` (a path, branch name, or PR URL/number that identifies the target), `target_title` (short human-readable title, e.g. spec name or PR title), `context` (background context: what to focus on, constraints, definition of done) | `instructions`, `mode` (`context-only` — optional; by default, on the same machine, the reviewer's worktree is mirrored from your working tree including uncommitted changes, so it reads the actual source. Pass `context-only` to opt out and treat the submitted context as authoritative) | Once, at the start of a review task. |
 | `submit_review_round` | `flow_run_id`, `context` | `instructions` | After addressing findings. Pass the same `flow_run_id` and the updated context. |
 | `get_review_flow_status` | `flow_run_id` | — | Poll or check the current status of a flow (running, waiting, completed, failed). |
 | `close_review_flow` | `flow_run_id` | — | Only after the reviewer returns `NO FINDINGS`. |
@@ -76,14 +78,14 @@ if FINDINGS:
 ## Example (code review)
 
 ```
-# Step 1 — start (all five required args must be provided; mode=context-only is required for code-review)
+# Step 1 — start (all five required args must be provided; on the same machine the reviewer sees
+# your working tree, uncommitted changes included — pass mode="context-only" to opt out)
 start_review_flow(
   kind="code-review",
   target_kind="branch",
   target_ref="feature/add-null-check",
   target_title="Add null check on user input",
-  context="Review the diff on this branch for correctness and adherence to project conventions.",
-  mode="context-only"
+  context="Review the diff on this branch for correctness and adherence to project conventions."
 )
 # → returns flow_run_id, e.g. "flow_abc123"
 # → reviewer returns FINDINGS: missing null check on line 42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kurrent/kcap",
-  "version": "0.8.18",
+  "version": "0.9.1",
   "description": "CLI companion for Kurrent Capacitor — records and visualizes Claude Code sessions",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -14,12 +14,12 @@
     "postinstall": "node bin/postinstall.js"
   },
   "optionalDependencies": {
-    "@kurrent/kcap-darwin-arm64": "0.8.18",
-    "@kurrent/kcap-linux-x64": "0.8.18",
-    "@kurrent/kcap-linux-arm64": "0.8.18",
-    "@kurrent/kcap-linux-musl-x64": "0.8.18",
-    "@kurrent/kcap-linux-musl-arm64": "0.8.18",
-    "@kurrent/kcap-win-x64": "0.8.18"
+    "@kurrent/kcap-darwin-arm64": "0.9.1",
+    "@kurrent/kcap-linux-x64": "0.9.1",
+    "@kurrent/kcap-linux-arm64": "0.9.1",
+    "@kurrent/kcap-linux-musl-x64": "0.9.1",
+    "@kurrent/kcap-linux-musl-arm64": "0.9.1",
+    "@kurrent/kcap-win-x64": "0.9.1"
   },
   "files": [
     "bin/",