Session recall

When you ask your coding agent “have we worked on this before?”, “why did we pick X over Y last time?”, or “who decided this?”, it should be able to answer — not just from the current chat, but from every Capacitor-recorded session you have access to.

That’s what session recall does. The kapacitor mcp sessions stdio server gives the agent three tools — search, summarise, drill in — so it can find the relevant past session, orient itself, and pull the exact decision context into the conversation without you leaving it.

Already know the session ID?

Session recap is the simpler path — one CLI call, no agent in the loop. Recall is for the I don’t know which session yet case.

Unlike PR review, which is scoped to a single PR’s transcripts, session recall searches across every session you can see, defaulted to the repo you’re currently in.

The Kapacitor plugin (installed by kapacitor setup) auto-registers the server for both Claude Code and Codex CLI — verify with claude mcp list or codex mcp list. For other MCP-aware clients, spawn kapacitor mcp sessions over stdio directly.

How scoping works

The server is repo-aware. It resolves the current working directory to a repo hash at startup, so when an agent invokes search_sessions without an explicit repo argument, results are scoped to this repo by default. cd into a project before spawning your agent and the scoping happens automatically.

Auth is shared with the rest of the CLI: tokens live at ~/.config/kapacitor/tokens.json and refresh automatically for Auth0 / GitHub App profiles. If the cached token is missing or unrecoverable, the MCP tools return “Not logged in. Run ‘kapacitor login’ on the host shell.” — fix that once on the host and the agent can retry.

What the agent gets

Three tools, designed to be chained: search → orient → drill in.

search_sessions

Free-text search over titles and transcripts (including subagent transcripts).

Argument	Notes
query	FTS string. Optional when author is set.
author	GitHub username or display name. Fuzzy match.
author_github_id	Explicit numeric ID. Takes precedence over author.
repo	"all" for cross-repo, "<owner>/<name>", or a 16-hex repo hash. Defaults to the cwd repo.
limit	1–50. Default 10.
offset	0–500. Default 0.

Each hit comes back with session_id, title, owner, a highlighted snippet, and — for transcript hits — hit_event_index and agent_id so the agent can jump straight to the exact event.

When the query matches a subagent transcript, agent_id identifies which subagent stream the hit came from. Pass it through to get_session_transcript to drill into that stream specifically.

get_session_summary

Pulls back a concise { summary_text, plan } for a session. Use this first to orient before reading raw transcript.

Argument	Notes
session_id	Required. Returned by search_sessions.

The summary text is the same “what was done” narrative shown by kapacitor recap (and on the dashboard). The plan, when present, is whatever the agent committed to before executing.

get_session_transcript

Speaker-tagged events from a session, formatted for an LLM to read.

Argument	Notes
session_id	Required.
around_event	Center the window on this event index (from a search hit).
agent_id	Required alongside around_event if the hit was in a subagent.
before	Events before around_event. Default 5.
after	Events after around_event. Default 15.
limit	When around_event is unset. Default 50, max 200.
offset	When around_event is unset. Default 0.
chain	Include continuation-chain metadata. Default false.
include_thinking	Include assistant thinking blocks. Default false.

The default window (50 events from the start) is meant for “what is this session about?”. The windowed mode (around_event + before / after) is meant for “what exactly did they say at the moment of the hit?”.

A typical chain

The agent has installed the MCP server and is sitting in a repo. The user asks: “didn’t we already debate using a queue here? what did we land on?”

1. search: search_sessions({ query: "queue vs direct call" }) — defaulted to the current repo. The hit’s snippet mentions a decision and points at session_id: abc…, hit_event_index: 142.
2. orient: get_session_summary({ session_id: "abc…" }) — confirms the session was about exactly this debate, gives the gist.
3. drill in: get_session_transcript({ session_id: "abc…", around_event: 142, before: 10, after: 10 }) — the exact turn where the decision was made, with surrounding context.

The agent now has enough grounding to give a real answer, citing the prior session.

Visibility

Every tool respects the same visibility rules as the dashboard:

• Sessions you can’t see in the dashboard, the agent can’t query through this server.
• Private sessions are only accessible to the owner.
• Hidden sessions are excluded for everyone except the owner.

In particular, get_session_summary is now visibility-gated end-to-end. (It used to be possible to read a session’s narrative if you knew its ID. That gap was closed alongside this server.)

Sharing a session via the dashboard’s share popover immediately makes it queryable for the recipients.

Cross-repo searches

By default, search_sessions is scoped to the cwd’s repo. Two ways to broaden:

• repo: "all" — search every repo you have access to.
• repo: "owner/name" — search one specific other repo by GitHub slug, or pass a 16-hex repo hash if you already have one.

Empty / whitespace repo is treated the same as omitting it, so the cwd default still kicks in.

Prompts that trigger cross-repo search

You don’t drive repo: "all" or repo: "owner/name" directly — you ask the agent in natural language and it picks the right argument from the question. Phrasings that work well:

Across all your repos. Anything that hints “anywhere”, “any of our projects”, or names a technology / pattern rather than a project:

• “Where have we used pgvector before? Check all our repos.”
• “Have I ever worked with the Stripe webhooks API? Look across everything.”
• “Find any past session — any repo — where we debated event sourcing vs CRUD.”

In a specific other repo. Name the repo explicitly:

• “Search the kurrent-io/kurrentdb repo for sessions about replication lag.”
• “Did we hit this same bug in acme/checkout-svc? Recall any session that touched it.”

Stay in the current repo (the default). Just ask the question — no repo phrasing needed:

• “Have we worked on this rate-limiter before?”
• “Why did we pick channels over a queue here? Find the session where we decided.”

If the agent’s first cut returns nothing, nudge it: “try across all repos” or “check owner/repo too”.

Related

• Session recap — the same data, but for the “I know the session ID” case. Runs from the CLI; no agent needed.
• PR review — same MCP pattern, scoped to a single PR’s transcripts.
• Visibility & sharing — controls who can find which sessions.