- New skill ckb-add-conversation: on request, copies the session's Claude Code transcript (JSONL) into raw/saved-conversations/<date>/ with a readable Markdown rendering and an index.md; answers "did we discuss X" from those files. Saved conversations stay outside retrieval and ingest. - AGENTS.md: directory contract, cascade note, routing row, disambiguation, Rule E session-end ask (save only on a yes). - ckb-retrieve, ckb-ingest, ckb-reset (tier 3), ckb-init know the folder. - Docs, both READMEs, CHANGELOG, VERSION; smoke test renders a fixture transcript against a golden file. - .gitignore: ideas/ local scratch folder for template ideas. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
7.8 KiB
| name | description |
|---|---|
| ckb-add-conversation | Save the current Claude Code conversation (or an earlier session of this project) verbatim into raw/saved-conversations/<YYYY-MM-DD>/ as the original JSONL plus a readable Markdown rendering, and search those saved conversations when asked what was discussed or instructed before. Saved conversations never enter retrieval or the wiki on their own. Use for "save this conversation", "save the chat", "archive this session", "keep a copy of our talk", and for "did we discuss X", "what did I tell you about X", "what did I ask you to do about Y last time", "find the conversation where ...". |
Add conversation skill
Purpose
Keep a verbatim copy of a conversation inside the KB, on the user's request only. Two jobs:
- Save — copy the session's transcript file into
raw/saved-conversations/<YYYY-MM-DD>/and render it as Markdown. - Recall — when the user asks whether something was discussed or what instruction they gave earlier, search the saved conversations and answer from them, quoting the exact exchange.
What this skill is not:
- Not retrieval.
raw/saved-conversations/is outside the cascade.ckb-retrievenever reads it, lint never fingerprints it, and nothing in it counts as a source for a wiki page until it has been ingested. - Not ingest. A saved conversation becomes wiki knowledge only when the user
copies its
.mdintoraw/inbox/and says "Ingest" — the copy is theirs to make, so the choice of what enters the wiki stays explicit. - Not automatic. The agent asks at session end (Rule E) and saves only on a clear yes. Never save because a session "seems important".
Where transcripts come from
Claude Code writes every session as a JSONL file:
<config>/projects/<encoded-cwd>/<session-id>.jsonl
<config> is $CLAUDE_CONFIG_DIR when set, else ~/.claude.
<encoded-cwd> is the KB's absolute path with every character that is not a
letter or digit replaced by - (/home/me/My KB → -home-me-My-KB). The
file still being written is the current session, so "most recently modified"
is the right default. The script does this lookup; the fallback section shows
it by hand.
How to run this skill — Save
Step 1 — Confirm the target
If the user said "save this conversation", the target is the current session. If they named an earlier one ("save yesterday's session", "the one about billing"), list candidates and let them pick:
<python> .agents/skills/ckb-add-conversation/scripts/save_conversation.py --list
Each row shows a session-id prefix, last activity, size, user-turn count and
the title. Pass the chosen prefix with --session <prefix>.
Step 2 — Say what will be captured
Before writing, tell the user in one or two sentences that the transcript is
verbatim: every message, every tool call, and the first few hundred characters
of every tool result, including file contents the agent printed during the
session. It will be a tracked file in the repo. If the session touched
anything secret-looking (.env, keys, tokens, credentials, personal data),
say so and let them decide. Thinking blocks are never rendered into the
Markdown but remain in the JSONL copy.
Step 3 — Save
<python> .agents/skills/ckb-add-conversation/scripts/save_conversation.py # current session
<python> .agents/skills/ckb-add-conversation/scripts/save_conversation.py --session <prefix>
<python> .agents/skills/ckb-add-conversation/scripts/save_conversation.py --title "Short name" # override the derived title
The script writes, under raw/saved-conversations/<today>/:
<slug>_<sid8>.jsonl— byte-for-byte copy of the transcript<slug>_<sid8>.md— readable rendering: a metadata table (session id, start and last-message times, working directory, branch, Claude Code version, turn counts, sha256 of the JSONL), then the exchange in order. User and assistant text verbatim; tool calls as one-line> **Tool:**notes; tool results truncated; harness<system-reminder>blocks stripped; thinking omitted.
and updates raw/saved-conversations/index.md (one row per session, newest
first; re-saving a session that continued replaces its files and its row).
The slug comes from Claude Code's own session title when present, otherwise
from the first user line. --dry-run shows the paths without writing.
Step 4 — Report and log
Report the two paths, the title and the turn counts the script printed. Then
append a line to today's workload/ summary naming the saved file. Nothing
under wiki/ changed, so wiki/log.md is not touched — Rule B covers
the wiki only.
If the user wants the conversation's content in the wiki, say so plainly:
copy the .md into raw/inbox/ and say "Ingest". Do not copy it for them
unless they ask.
Without Python
Resolve <python> as AGENTS.md §3 describes. If no interpreter runs, copy
the JSONL by hand and skip the Markdown rendering:
CFG="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
PROJ="$CFG/projects/$(pwd | sed 's/[^A-Za-z0-9]/-/g')"
SRC=$(ls -t "$PROJ"/*.jsonl | head -1) # current session
DEST="raw/saved-conversations/$(date +%F)"; mkdir -p "$DEST"
cp "$SRC" "$DEST/conversation_$(basename "$SRC" .jsonl | cut -c1-8).jsonl"
Add a row to raw/saved-conversations/index.md by hand (create the file
with the header the script would write, see INDEX_HEADER in the script).
Tell the user once that the readable .md can be produced later by re-running
the script with --from <that jsonl> once Python is available.
How to run this skill — Recall
Triggers: "did we discuss X", "have we talked about X before", "what did I tell you about X", "what instructions did I give about Y", "what did I ask you to do last time", "find the conversation where ...".
- Read
raw/saved-conversations/index.md. If it is missing or empty, say no conversations have been saved and stop — do not fall back toworkload/or the wiki as if they were transcripts (they are summaries, offer them as such). - Search the
.mdrenderings, not the JSONL:
Try two or three phrasings; people rarely reuse their exact words.grep -ril "<term>" raw/saved-conversations/*/*.md grep -n -i -B2 -A6 "<term>" raw/saved-conversations/<date>/<file>.md - For an "instruction I gave" question, prefer
## Userblocks over## Assistantones — the user's own words are the instruction, the assistant's restatement is not. - Answer with the exact exchange quoted, attributed as
— `raw/saved-conversations/<date>/<file>.md`, under "User — <timestamp>", and the date. If nothing matches, say that no saved conversation mentions it, and name the date range the saved conversations cover so the user knows whether the gap is "never discussed" or "not saved". - Never promote a recalled instruction into
wiki/on the strength of the transcript alone. If it deserves to be durable, offerckb-decide(for a decision) or ingest (for knowledge) as the next step.
Edge cases
- No transcript directory (exit code 2): the KB is being driven by
something other than Claude Code, or
CLAUDE_CONFIG_DIRpoints elsewhere. Report the path the script looked in and ask the user for the transcript file; then use--from <file>. - Ambiguous
--sessionprefix: the script lists the matches; pass a longer prefix. - Same session saved twice in one day: files and index row are replaced,
the script prints
updated(orunchangedwhen nothing grew). A session saved again on a later day gets a new dated folder; both stay. - Subagent turns are rendered with a
(subagent)marker on the heading. - Very long tool results are cut at 400 characters in the Markdown; the JSONL has them in full.
ckb-resettreatsraw/saved-conversations/as tier 3 source material: asked about, never deleted silently.