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>
454 lines
19 KiB
Python
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())
|