ckb/.agents/skills/ckb-add-conversation/scripts/save_conversation.py
Michał Kopeć cb56da51e5 Template 1.22.0: agent-knowledge release 1
Seven features from the 2026-10-31 agent-knowledge research, no schema
change (kb_schema_version stays 1.5):

- F1 session-start hook: session_start.py --hook, start_hook.py, opt-in
  via session.start_hook in ckb.yaml (D-0011)
- F2 kept answers in outputs/answers/, lint check 16 (D-0013)
- F3 ingest check-in before writing; batch mode skips it
- F5 open threads in workload notes, collected at session start (D-0012)
- F6 dedup_inbox.py: duplicates reported before ingest
- F19 lint check 15 for secrets and <private> spans, --secrets before
  every sync commit, redaction in saved conversations (D-0013)
- F20 context budget: lint_report.py --budget, budget in ckb.yaml

Smoke test covers every new script. Docs updated in EN and PL.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 19:25:02 +01:00

454 lines
19 KiB
Python

#!/usr/bin/env python3
"""Save a Claude Code conversation into raw/saved-conversations/.
Copies the session's transcript (the JSONL Claude Code keeps under its config
directory) into raw/saved-conversations/<YYYY-MM-DD>/ and writes a readable
Markdown rendering next to it, then updates raw/saved-conversations/index.md.
save_conversation.py # save the current (most recently written) session
save_conversation.py --list # list this project's sessions, newest first
save_conversation.py --session <id> # save a specific session (id or unique prefix)
save_conversation.py --from <file.jsonl> # save a transcript file given explicitly
save_conversation.py --from-hook # Claude Code hook: read {"transcript_path": ...} from stdin
save_conversation.py --title "..." # override the derived title for this save only
save_conversation.py --set-title "..." # remember a title for the session (tmp/conversation-titles/), then exit
save_conversation.py --dry-run # say what would be written, write nothing
Anything between <private> and </private> (or to the end of the message when
the tag is never closed) is replaced by <private>[redacted]</private> in both
the saved JSONL and the Markdown. Lines without a span stay byte-identical.
Title precedence: --title, then the title stored by --set-title for this
session, then Claude Code's own custom (/rename) or AI title, then the first
user line.
Python 3.8+, standard library only. Exit 0 on success, 1 on a usage/lookup
error, 2 when nothing was found to save.
"""
import argparse
import hashlib
import json
import os
import re
import subprocess
import sys
from datetime import datetime, timezone
from pathlib import Path
DEST_ROOT = Path("raw") / "saved-conversations"
TITLES_DIR = Path("tmp") / "conversation-titles" # per machine (tmp/ is gitignored); the Stop hook reads it
RESULT_CHARS = 400
INPUT_CHARS = 200
SYSTEM_REMINDER = re.compile(r"<system-reminder>.*?</system-reminder>\s*", re.DOTALL)
PRIVATE_SPAN = re.compile(r"<private>.*?(?:</private>|\Z)", re.DOTALL | re.IGNORECASE)
PRIVATE_MARK = "<private>[redacted]</private>"
# ---------------------------------------------------------------- identity
def git_identity(root: Path) -> str:
"""'Name <email>' from the repo's git config, '' when unavailable."""
vals = []
for key in ("user.name", "user.email"):
try:
out = subprocess.run(["git", "config", key], cwd=str(root), capture_output=True,
text=True, timeout=5).stdout.strip()
except (OSError, subprocess.SubprocessError):
out = ""
vals.append(out)
name, email = vals
if name and email:
return f"{name} <{email}>"
return name or email or ""
# ---------------------------------------------------------------- locating
def config_dir() -> Path:
env = os.environ.get("CLAUDE_CONFIG_DIR")
return Path(env).expanduser() if env else Path.home() / ".claude"
def project_dir_for(cwd: Path) -> Path:
# Claude Code encodes the working directory by replacing every character
# that is not a letter or digit with "-": "/home/me/My KB" -> "-home-me-My-KB".
encoded = re.sub(r"[^A-Za-z0-9]", "-", str(cwd))
return config_dir() / "projects" / encoded
def list_sessions(pdir: Path):
out = []
for f in pdir.glob("*.jsonl"):
st = f.stat()
out.append({"id": f.stem, "path": f, "mtime": st.st_mtime, "size": st.st_size})
out.sort(key=lambda s: s["mtime"], reverse=True)
return out
def pick_session(sessions, wanted):
if not wanted:
return sessions[0] if sessions else None
hits = [s for s in sessions if s["id"].startswith(wanted)]
if len(hits) == 1:
return hits[0]
if not hits:
sys.exit(f"error: no session starting with {wanted!r} in this project")
sys.exit("error: ambiguous session prefix; matches: " + ", ".join(h["id"] for h in hits))
# ---------------------------------------------------------------- parsing
def redact(value):
"""Replace every <private> span in every string of a parsed JSON value."""
if isinstance(value, str):
return PRIVATE_SPAN.sub(PRIVATE_MARK, value)
if isinstance(value, list):
return [redact(v) for v in value]
if isinstance(value, dict):
return {k: redact(v) for k, v in value.items()}
return value
def redact_jsonl(data: bytes) -> bytes:
"""The transcript with <private> spans removed. Only lines that carry a
span are re-serialised; every other line is kept byte for byte."""
out = []
for line in data.split(b"\n"):
if b"<private>" in line.lower():
try:
line = json.dumps(redact(json.loads(line)), ensure_ascii=False).encode("utf-8")
except ValueError:
line = PRIVATE_SPAN.sub(PRIVATE_MARK, line.decode("utf-8", "replace")).encode("utf-8")
out.append(line)
return b"\n".join(out)
def read_entries(path: Path):
entries = []
with path.open(encoding="utf-8", errors="replace") as fh:
for line in fh:
line = line.strip()
if not line:
continue
try:
entries.append(redact(json.loads(line)))
except json.JSONDecodeError:
continue
return entries
def session_meta(entries, path: Path):
meta = {"session_id": path.stem, "title": None, "cwd": None, "version": None,
"started": None, "ended": None, "user_turns": 0, "assistant_turns": 0,
"tool_calls": 0, "git_branch": None}
custom = None
for e in entries:
t = e.get("type")
if t == "ai-title" and e.get("aiTitle"):
meta["title"] = e["aiTitle"]
if t == "custom-title" and e.get("customTitle"): # /rename in Claude Code
custom = e["customTitle"]
if t in ("user", "assistant"):
ts = e.get("timestamp")
if ts:
meta["started"] = meta["started"] or ts
meta["ended"] = ts
meta["cwd"] = meta["cwd"] or e.get("cwd")
meta["version"] = meta["version"] or e.get("version")
meta["git_branch"] = meta["git_branch"] or e.get("gitBranch")
meta["session_id"] = e.get("sessionId") or meta["session_id"]
if t == "user" and not e.get("isMeta") and user_text(e):
meta["user_turns"] += 1
if t == "assistant":
blocks = (e.get("message") or {}).get("content") or []
if any(b.get("type") == "text" and b.get("text", "").strip() for b in blocks if isinstance(b, dict)):
meta["assistant_turns"] += 1
meta["tool_calls"] += sum(1 for b in blocks if isinstance(b, dict) and b.get("type") == "tool_use")
if custom:
meta["title"] = custom
return meta
def stored_title(root: Path, session_id: str):
"""Title remembered by --set-title for this session, or None."""
f = root / TITLES_DIR / f"{session_id}.title"
if f.is_file():
t = f.read_text(encoding="utf-8").strip()
return t or None
return None
def store_title(root: Path, session_id: str, title: str) -> Path:
d = root / TITLES_DIR
d.mkdir(parents=True, exist_ok=True)
f = d / f"{session_id}.title"
f.write_text(title.strip() + "\n", encoding="utf-8")
return f
def remove_stale_copies(dest_dir: Path, sid8: str, keep_base: str):
"""A re-save under a new title changes the slug; drop the old pair for this session."""
if not dest_dir.is_dir():
return
for f in dest_dir.iterdir():
if f.is_file() and f.stem.endswith(f"_{sid8}") and f.stem != keep_base and f.suffix in (".md", ".jsonl"):
f.unlink()
def user_text(entry):
"""Plain text a user typed in this entry, with harness reminders stripped."""
content = (entry.get("message") or {}).get("content")
parts = []
if isinstance(content, str):
parts.append(content)
elif isinstance(content, list):
for b in content:
if isinstance(b, dict) and b.get("type") == "text":
parts.append(b.get("text", ""))
text = "\n".join(parts)
text = SYSTEM_REMINDER.sub("", text).strip()
return text
def first_user_line(entries):
for e in entries:
if e.get("type") == "user" and not e.get("isMeta"):
t = user_text(e)
if t:
return t.splitlines()[0]
return ""
def slugify(s: str, limit=48) -> str:
s = re.sub(r"[^A-Za-z0-9]+", "-", s).strip("-").lower()
return s[:limit].rstrip("-") or "conversation"
def truncate(s: str, n: int) -> str:
s = s.replace("\r", "")
return s if len(s) <= n else s[:n].rstrip() + f" … [+{len(s) - n} chars]"
def summarize_tool_input(inp) -> str:
if not isinstance(inp, dict):
return truncate(json.dumps(inp, ensure_ascii=False), INPUT_CHARS)
for key in ("description", "command", "file_path", "pattern", "query", "skill", "prompt", "url"):
if key in inp and isinstance(inp[key], str):
return f"{key}: " + truncate(inp[key].strip().splitlines()[0] if inp[key].strip() else "", INPUT_CHARS)
return truncate(json.dumps(inp, ensure_ascii=False), INPUT_CHARS)
def result_text(block) -> str:
c = block.get("content")
if isinstance(c, str):
return c
if isinstance(c, list):
return "\n".join(b.get("text", "") for b in c if isinstance(b, dict) and b.get("type") == "text")
return ""
# ---------------------------------------------------------------- rendering
def render_markdown(entries, meta, rel_jsonl: str, digest: str, saved_on: str, author: str = "") -> str:
out = []
title = meta["title"] or first_user_line(entries) or "Conversation"
out.append(f"# {title}\n")
out.append("Saved conversation — a verbatim record kept outside retrieval. See `raw/saved-conversations/index.md`.\n")
out.append("| | |")
out.append("|---|---|")
out.append(f"| Session | `{meta['session_id']}` |")
if author:
out.append(f"| Author | {author} |")
out.append(f"| Started | {meta['started'] or '?'} |")
out.append(f"| Last message | {meta['ended'] or '?'} |")
out.append(f"| Saved on | {saved_on} |")
out.append(f"| Working directory | `{meta['cwd'] or '?'}` |")
if meta["git_branch"]:
out.append(f"| Git branch | `{meta['git_branch']}` |")
out.append(f"| Claude Code | {meta['version'] or '?'} |")
out.append(f"| Turns | {meta['user_turns']} user / {meta['assistant_turns']} assistant / {meta['tool_calls']} tool calls |")
out.append(f"| Raw transcript | `{rel_jsonl}` — sha256:{digest} |")
out.append("")
out.append("---\n")
last_role = None
for e in entries:
t = e.get("type")
if t not in ("user", "assistant"):
continue
side = " (subagent)" if e.get("isSidechain") else ""
ts = (e.get("timestamp") or "")[:16].replace("T", " ")
content = (e.get("message") or {}).get("content")
if isinstance(content, str):
content = [{"type": "text", "text": content}]
if not isinstance(content, list):
continue
for b in content:
if not isinstance(b, dict):
continue
kind = b.get("type")
if t == "user" and kind == "text":
if e.get("isMeta"):
continue
text = SYSTEM_REMINDER.sub("", b.get("text", "")).strip()
if not text:
continue
if last_role != "user":
out.append(f"## User{side} — {ts}\n")
last_role = "user"
out.append(text + "\n")
elif t == "user" and kind == "tool_result":
r = result_text(b).strip()
if not r:
continue
out.append("> **Result:** " + truncate(r, RESULT_CHARS).replace("\n", "\n> ") + "\n")
elif t == "assistant" and kind == "text":
text = b.get("text", "").strip()
if not text:
continue
if last_role != "assistant":
out.append(f"## Assistant{side} — {ts}\n")
last_role = "assistant"
out.append(text + "\n")
elif t == "assistant" and kind == "tool_use":
if last_role != "assistant":
out.append(f"## Assistant{side} — {ts}\n")
last_role = "assistant"
out.append(f"> **Tool:** `{b.get('name', '?')}` — {summarize_tool_input(b.get('input'))}\n")
# thinking blocks are deliberately not rendered
return "\n".join(out).rstrip() + "\n"
# ---------------------------------------------------------------- index
INDEX_HEADER = """# Saved conversations
Verbatim Claude Code transcripts saved on request by `ckb-add-conversation`.
They are **not** part of retrieval: `ckb-retrieve` never reads this folder.
Ask "did we discuss X" or "what did I ask you to do about Y" to search them.
To turn one into wiki knowledge, copy its `.md` into `raw/inbox/` and say "Ingest".
| Saved | Title | Session | Turns | Transcript |
|---|---|---|---|---|
"""
def update_index(index_path: Path, row: dict, dry_run: bool):
lines = index_path.read_text(encoding="utf-8").splitlines() if index_path.exists() else INDEX_HEADER.rstrip("\n").splitlines()
marker = f"`{row['session'][:8]}`"
lines = [l for l in lines if not (l.startswith("| ") and marker in l)]
new = (f"| {row['saved']} | {row['title']} | {marker} | {row['turns']} | "
f"[{row['md_name']}]({row['md_rel']}) · [jsonl]({row['jsonl_rel']}) |")
# keep newest first: insert right after the table header separator
try:
sep = next(i for i, l in enumerate(lines) if l.startswith("|---"))
lines.insert(sep + 1, new)
except StopIteration:
lines.append(new)
if not dry_run:
index_path.write_text("\n".join(lines).rstrip("\n") + "\n", encoding="utf-8")
# ---------------------------------------------------------------- main
def main(argv=None):
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("--list", action="store_true", help="list this project's sessions and exit")
ap.add_argument("--session", help="session id (or unique prefix) to save; default: most recently written")
ap.add_argument("--from", dest="from_file", help="save this transcript file instead of looking one up")
ap.add_argument("--from-hook", action="store_true",
help="read Claude Code hook JSON from stdin and save its transcript_path")
ap.add_argument("--title", help="override the derived title for this save only")
ap.add_argument("--set-title", metavar="TITLE",
help="remember TITLE for the session (current, --session or --from-hook) and exit without saving")
ap.add_argument("--author", help="'Name <email>' to record; default: the repo's git identity")
ap.add_argument("--root", default=".", help="KB root (default: current directory)")
ap.add_argument("--today", help="override the save date, YYYY-MM-DD (tests)")
ap.add_argument("--dry-run", action="store_true")
args = ap.parse_args(argv)
root = Path(args.root).resolve()
today = args.today or datetime.now().strftime("%Y-%m-%d")
if args.from_hook:
try:
hook = json.load(sys.stdin)
except (json.JSONDecodeError, ValueError):
sys.exit("error: --from-hook expects hook JSON on stdin")
args.from_file = hook.get("transcript_path")
if not args.from_file:
sys.exit("error: hook JSON carries no transcript_path")
if args.from_file:
src = Path(args.from_file).expanduser().resolve()
if not src.is_file():
sys.exit(f"error: {src} is not a file")
else:
pdir = project_dir_for(root)
if not pdir.is_dir():
print(f"no transcripts: {pdir} does not exist (CLAUDE_CONFIG_DIR={config_dir()})", file=sys.stderr)
return 2
sessions = list_sessions(pdir)
if args.list:
for s in sessions:
entries = read_entries(s["path"])
meta = session_meta(entries, s["path"])
when = datetime.fromtimestamp(s["mtime"]).strftime("%Y-%m-%d %H:%M")
shown = stored_title(root, s["id"]) or meta["title"] or first_user_line(entries)[:60]
print(f"{s['id'][:8]} {when} {s['size'] // 1024:6d} KB {meta['user_turns']:3d} turns {shown}")
return 0
chosen = pick_session(sessions, args.session)
if not chosen:
print(f"no transcripts in {pdir}", file=sys.stderr)
return 2
src = chosen["path"]
if args.set_title is not None:
if not args.set_title.strip():
sys.exit("error: --set-title needs a non-empty title")
f = store_title(root, src.stem, args.set_title)
print(f"title set: {args.set_title.strip()} (session {src.stem[:8]}, {f.relative_to(root).as_posix()})")
return 0
entries = read_entries(src)
meta = session_meta(entries, src)
if args.title:
meta["title"] = args.title
else:
meta["title"] = stored_title(root, meta["session_id"]) or stored_title(root, src.stem) or meta["title"]
title = meta["title"] or first_user_line(entries) or "Conversation"
data = redact_jsonl(src.read_bytes())
digest = hashlib.sha256(data).hexdigest()[:8]
dest_dir = root / DEST_ROOT / today
base = f"{slugify(title)}_{meta['session_id'][:8]}"
jsonl_path = dest_dir / f"{base}.jsonl"
md_path = dest_dir / f"{base}.md"
rel = lambda p: p.relative_to(root).as_posix()
author = args.author if args.author is not None else git_identity(root)
md = render_markdown(entries, meta, rel(jsonl_path), digest, today, author)
existed = jsonl_path.exists()
unchanged = existed and hashlib.sha256(jsonl_path.read_bytes()).hexdigest()[:8] == digest
if not args.dry_run:
dest_dir.mkdir(parents=True, exist_ok=True)
remove_stale_copies(dest_dir, meta["session_id"][:8], base)
jsonl_path.write_bytes(data)
md_path.write_text(md, encoding="utf-8")
update_index(root / DEST_ROOT / "index.md", {
"saved": today, "title": title.replace("|", "/"), "session": meta["session_id"],
"turns": meta["user_turns"], "md_name": md_path.name,
"md_rel": md_path.relative_to(root / DEST_ROOT).as_posix(),
"jsonl_rel": jsonl_path.relative_to(root / DEST_ROOT).as_posix(),
}, args.dry_run)
verb = "would save" if args.dry_run else ("unchanged" if unchanged else ("updated" if existed else "saved"))
print(f"{verb}: {rel(md_path)}")
print(f" {rel(jsonl_path)} ({len(data) // 1024} KB, sha256:{digest})")
print(f" title: {title}")
print(f" {meta['user_turns']} user turns, {meta['assistant_turns']} assistant turns, {meta['tool_calls']} tool calls")
return 0
if __name__ == "__main__":
sys.exit(main())