@kurrent/kcap 0.8.17 → 0.9.0

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

@@ -1,5 +1,5 @@
 {
   "name": "kcap",
-  "version": "0.8.17",
+  "version": "0.9.0",
   "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 hosted reviewer agent through your daemon; requires `kcap login` and a running daemon with this repo checked out (the tools are inert otherwise)."
+      "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."
+    },
+    "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/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

@@ -1,20 +1,32 @@
 ---
 name: review-flows
 description: >-
-  This skill should be used when the user asks to "review this spec",
-  "review this design", "review my PR", "code review", "get this reviewed",
-  "re-review", "start a review flow", "review flow", "submit for review",
-  or wants structured iterative review with findings and sign-off.
+  This skill should be used ONLY when the user explicitly asks to run a
+  structured review *flow* — e.g. "start a review flow", "submit this for
+  review", "re-review after I address findings", or wants an iterative review
+  loop run by a separate reviewer that continues until sign-off. Do NOT use
+  this skill (and do NOT call the flows MCP tools) for an ordinary review
+  request such as "review my PR", "review this diff/spec/design", or "code
+  review" where the user just wants you to review it yourself — perform that
+  review directly instead.
 ---
 
 # Review Flows
 
-Use `kcap mcp flows` MCP tools to run structured review loops for specs/designs and PR/code work. A review flow submits your work to a reviewer, collects findings, lets you address them, and keeps iterating until the reviewer returns `NO FINDINGS`.
+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.
 
-## When to use
+## When NOT to use this skill / these tools
 
-- Reviewing a spec or design document → use `kind: "spec-review"`
-- Reviewing code changes or a pull request → use `kind: "code-review"`
+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.
+
+Only start a flow when the user explicitly asks for a review *flow* — e.g. "start a review flow", "submit this for review", "get an independent review", or "re-review after I address the findings".
+
+## Choosing the flow kind
+
+Once the user has explicitly opted into a flow (see above), pick the `kind`:
+
+- Spec or design document → `kind: "spec-review"`
+- Code changes or a pull request → `kind: "code-review"`
 
 ## If the flows MCP tools are not loaded
 
@@ -56,7 +68,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`. |
@@ -64,14 +76,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.17",
+  "version": "0.9.0",
   "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.17",
-    "@kurrent/kcap-linux-x64": "0.8.17",
-    "@kurrent/kcap-linux-arm64": "0.8.17",
-    "@kurrent/kcap-linux-musl-x64": "0.8.17",
-    "@kurrent/kcap-linux-musl-arm64": "0.8.17",
-    "@kurrent/kcap-win-x64": "0.8.17"
+    "@kurrent/kcap-darwin-arm64": "0.9.0",
+    "@kurrent/kcap-linux-x64": "0.9.0",
+    "@kurrent/kcap-linux-arm64": "0.9.0",
+    "@kurrent/kcap-linux-musl-x64": "0.9.0",
+    "@kurrent/kcap-linux-musl-arm64": "0.9.0",
+    "@kurrent/kcap-win-x64": "0.9.0"
   },
   "files": [
     "bin/",