khive-pack-session 0.13.0

Session verb pack - store/list/resume/export over the notes substrate
Documentation

khive-pack-session

Session pack: registers the session note kind and seven agent-facing verbs for storing and retrieving agent-session records (transcripts or summaries) over the notes substrate (ADR-083).

Verbs

  • session.store(content, title?, provider?, provider_session_id?, tags?) — persist a session record. provider_session_id is the provider-native continuity anchor (not a khive UUID); (provider, provider_session_id) is the strongest grouping key when both are present.
  • session.list(limit?, offset?, provider?, agent_id?, since?) — browse stored sessions, newest first. agent_id matches the legacy properties.agent_id field and since is an inclusive RFC 3339 creation timestamp. Summaries omit content.
  • session.resume(id) — fetch one session's full content by full UUID or 8+ hex short prefix.
  • session.export(id, format?) — serialize a session as json (default) or markdown.
  • session.search(query, limit?, since?, source?, cwd?) — tenant-scoped mirror search. The public handler remains unavailable until transcript deletion and resume/export continuity support are available.
  • session.stats() — database-wide session mirror row and storage diagnostics.
  • session.vacuum() — explicit SQLite compaction, with before/after sizes when the post-commit measurement remains available.
request(ops="session.store(content=\"...\", provider=\"codex\", provider_session_id=\"abc\")")
request(ops="session.list(limit=20, provider=\"codex\")")
request(ops="session.list(agent_id=\"lambda:worker\", since=\"2026-08-01T00:00:00Z\")")
request(ops="session.resume(id=\"a1b2c3d4\")")
request(ops="session.export(id=\"a1b2c3d4\", format=\"markdown\")")

Storage

Sessions stored through the four note verbs are kind=session notes on the shared notes substrate. notes.name holds the optional title, notes.content holds the verbatim payload, and notes.properties holds provider, provider_session_id, and tags. Handlers go through the public runtime seam (runtime.core(), create_note, query_notes_filtered, resolve_prefix, resolve_primary) rather than direct SQL. The separate session mirror has pack-owned SQL tables, a versioned identity migration, and an FTS5 index; see ADR-117a mirror identity.

Out of scope for this slice

The digester/summarization pipeline is cloud-side. session.import, tiering, and billing are deferred; see ADR-083. The session mirror (transcript parsing and ingestion into session_messages) is a separate, already-shipped concern — see ADR-080 §6. After its startup discovery pass, the mirror caches directory listings, polls actively growing transcripts directly, and samples cold transcripts through fixed round-robin budgets. Quiet-tick metadata work therefore stays bounded as the historical transcript corpus grows; directory changes prioritize their cold files, with the ordinary bounded sweep covering filesystems where append does not update parent-directory mtime. The priority ordering is bounded but not fair under continuous directory churn: repeated changes can keep the priority queue ahead of the ordinary cold sweep, while productive cold-file metadata probes remain capped at 256 per tick.

Where this sits

khive-pack-session sits in the pack tier alongside khive-pack-kg (a REQUIRES dependency for the session note kind's substrate) and is one of the packs loaded by default in khive-mcp.

License

Apache-2.0.