Index and select sessions

Sessions are read from each harness's transcripts into a local SQLite index.

honed sessions --index sessions.sqlite sync logs/codex-training     # register the folder, read it
honed sessions --index sessions.sqlite sync                          # later: read what changed
honed sessions --index sessions.sqlite query 'harness:codex select:session'
honed sessions --index sessions.sqlite trajectories <session>
honed sessions --index sessions.sqlite render <session> --trajectory 0

The same from Python:

from honed.sessions import Sessions

with Sessions("sessions.sqlite") as sessions:
    source = sessions.add("logs/claude-training")            # detects the harness, synchronizes
    records = sessions.list(source=[source.id])               # newest first
    session = sessions.get(records[0].id)                     # any ID, native ID, or unique prefix

Trajectories

A trajectory is one user prompt and the subsequent recorded work in a single thread. The split is made independently for each event stream (source_id, session_id, run_id, and transcript segment); events from a parent and child thread are never stitched into one trajectory. Events before the first prompt remain unassigned. session.trajectories exposes the split, and session.through(trajectory) selects a session prefix only when the session has one event stream; it raises an ambiguity error when multiple run or transcript streams are present.

Finding sessions

from honed.sessions.scanner import ShellCommand, SkillUsage

hits = sessions.search("SyntaxError", kind="tool_result", status="failure")
used = {m.session_id for m in sessions.match(ShellCommand(contains="graphify query"))}
records = [r for r in sessions.list() if r.id in used]

match runs behavioural patterns over complete event sequences (loops, abandoned fixes, ignored instructions, shell commands, skill usage). A match is a signal to inspect, not proof of a cause.

Thread families

Honed uses these terms for different boundaries:

Honed term Definition Boundary and caveat
Session An indexed transcript container. Its session_id is taken from a harness-native conversation ID or, when unavailable, an adapter fallback. One session can contain multiple threads (Claude Code). A delegated thread can instead be a separate session (Codex and OpenCode). “Session” therefore does not mean the same native object in every harness.
Thread One independently ordered execution stream. Currently represented by a normalized run_id; all events with that ID belong to the stream. Honed’s thread is a common abstraction and may map to a native agent, thread, or session.
Trajectory One user prompt and its recorded response work within one thread. Prompt splitting is done per stream. It does not join parent and child activity, even if they overlap in time.
Parent / child A directed relationship between two threads: the child records the parent thread ID. These are direct links, not a stored root-to-leaf path. Links may cross sessions. A link identifies lineage, but does not necessarily identify the exact tool call that spawned the child.
Family The selected thread’s highest available linked parent plus its known descendants. Family membership follows indexed parent links. The root is derived from those links; ancestors are not copied onto every thread. A missing parent record can make the family incomplete.

parent_id and child_ids are direct thread IDs. None means that no parent link was recorded for that thread; it does not prove that the harness had no parent. A thread with a parent ID whose parent is absent from the index is not a root_thread. A family root is the family member whose parent is outside the included family; when an ancestor is missing from the index, this boundary thread can still have a non-null parent_id. root_thread means a thread with no recorded parent link, not necessarily the harness’s designated “main agent.”

Mapping harness records to Honed

The adapters map transcript identities and links into Honed’s session_id, run_id, and parent_run_id. The table describes current adapter behavior, not a claim that the harnesses use the same underlying concept.

Harness Native record used for Honed session Native record mapped to Honed thread Parent/child mapping and current limits
Claude Code sessionId; child-agent files use the enclosing session directory. Main transcript and each subagents/agent-*.jsonl file become separate threads in that session. The adapter links each child-agent thread to the main thread based on file layout. It does not retain nested child-to-child parentage, so nested agents appear as children of the main thread. This link is adapter-inferred from layout.
Codex session_meta.payload.id (or session_id). Each native thread ID becomes a Honed session with its own main thread. source.subagent.thread_spawn.parent_thread_id becomes the child thread’s parent link. The family crosses Honed session boundaries. Both parent and child records must be indexed to inspect both streams.
OpenCode Exported info.id. Each exported session becomes a Honed session with a main thread. Exported info.parentID (also accepted as parentId) becomes the parent link. Parent and child are separate Honed sessions; both exports must be indexed for a complete family.
Pi The JSONL session header’s id. The current adapter maps the session to one main thread. Per-record parentId is retained as event-level native metadata; it is not converted into thread parentage. Pi history branching is therefore not represented as agent delegation in the current thread family. Extension-created workers have no standardized link in this adapter.
Antigravity conversation_id, falling back to an ID derived from the transcript path. The current adapter maps the transcript to one main thread. The adapter does not currently extract a parent-thread link for delegated work. Tool steps remain events in the conversation thread; separate, unlinked transcripts cannot be safely attached to a family.

Honed’s normalized run_id is generated from the adapter’s session identity and agent identity; it is not necessarily a native ID. parent_run_id is projected to Thread.parent_id, and reverse links produce child_ids. Claude’s parent link is inferred from file layout; Codex and OpenCode adapters use explicit parent IDs from their records. Pi branching metadata and Antigravity relationships are not converted into thread links by the current adapters. Treat other lineage as unknown until an adapter can extract it reliably.

from honed.sessions import DecisionTrace, Sessions, WeightedPatternView, WorkGraph
from honed.sessions.scanner import ShellCommand

with Sessions("sessions.sqlite") as sessions:
    session = sessions.get("<session-id>")
    session.threads            # Threads in this transcript container
    session.root_threads       # Threads with no recorded parent link
    session.root_thread        # Convenience when there is exactly one root
    thread = session.thread("<run-id>")

    # Parent and child links are direct IDs; they can cross session boundaries.
    parent = sessions.thread(thread.parent_id) if thread.parent_id else None
    children = [sessions.thread(child_id) for child_id in thread.child_ids]

    family = sessions.family("<session-id-or-run-id>")
    matches = family.match(ShellCommand(contains="pytest"))
    patterns = WeightedPatternView(family.threads, case_scope="thread", pattern_lengths=(2, 3))
    graph = WorkGraph(thread)
    trace = DecisionTrace(thread)

Sessions.threads() lists all indexed threads, including threads whose parent is in another session; Sessions.root_threads() selects those without a recorded parent. Sessions.thread(reference) resolves a run ID. sessions.family(reference, exclude_root=False) follows parent links to build the known family and includes its derived root by default; exclude_root=True omits that thread. From the command line, honed sessions query 'family:<reference> select:thread' lists a family (add at:child to leave its root out). Analyses receive a selected thread or an explicit thread collection; they do not merge parent and child event streams into a single timeline. Session, Thread, and Trajectory implement EventSequence, so graph constructors accept any of them. A graph from a multi-stream Session keeps components and signal detection within each stream; it omits the global conversation overview because those streams have no single total order.

Graphs of what a query selected

honed sessions graph <kind> (short: honed s g <kind>) reads the results of honed sessions query --json (or session and run IDs, one per line) from stdin and graphs them:

  • workgraph: one graph per session or thread: its events, tool calls and signals.
  • decision-trace: one graph per session or thread: its decisions and what they were based on.
  • weighted: one view across all: counted activity sequences and their support.
  • aeg: one view across all: the Abstract Execution Graph (states, loops, outcomes, failure modes, critical steps, archetypes and drift).

The query decides what is graphed. select:session graphs whole sessions (for aeg, their root threads), select:thread graphs those threads (add at:root for main threads only), and an event match stands for the thread it occurred in. honed sessions query returns 50 results unless the query says count:N.

honed s q --json 'harness:codex select:session count:50' | honed s g weighted
honed s q --json 'harness:codex select:session' | honed s g weighted --pattern-length 2 --pattern-length 3
honed s q --json 'session:abc123 select:session' | honed s g workgraph -o mermaid
honed s q --json 'shell.startswith:pytest status:failure' | honed s g aeg --export artifacts/aeg

Every kind prints Markdown by default, or -o json|mermaid (and sankey for aeg); for the per-session kinds -o mermaid prints one graph, so it needs a single result. --export DIR writes report files (to DIR/<kind>/) instead; add -o to print as well. --png (not for aeg) also renders PNGs when Mermaid CLI (mmdc) is installed. Each kind has its own options: see honed s g <kind> --help.

Weighted patterns report each pattern's occurrence count and number of distinct cases, with source event IDs for tracing examples. Windows are counted only within one recorded run stream; unrelated runs are never joined, and an observed sequence does not establish causation. The default case is a whole session; --case-scope trajectory uses each prompt trajectory. Case support is descriptive, not a significance test. Use example event IDs with honed sessions show to inspect source records.

The AEG adds --abstraction, --compare, --llm, --judge N (model: HONED_JUDGE_MODEL), --revisions PROJECT (drift by release) and --gold FILE.

Querying graph artifacts

An export directory is an artifact: next to each kind's reports in DIR/<kind>/ it holds graphs.sqlite, every graph exported into it in one model, and manifest.json, what each kind was built from and how. Export several kinds into one directory and query them together; exporting a kind again replaces only that kind.

The model: graphs; their nodes and edges, each with a kind, a label (an AEG state, a weighted activity, a WorkGraph event kind) and properties; walks, one case's ordered path through the nodes; occurrences, where a node or edge happened (walk, step, time, event IDs); and annotations, the AEG's findings and critical steps and the WorkGraph's signals.

honed sessions graph query DIR… 'QUERY' (short: honed s g q) uses the syntax of session queries. Leading directories are the artifacts (a parent finds every artifact below it); select: returns graphs, nodes (default), edges, walks, occurrences, annotations, sessions, threads or events.

honed s q --json 'harness:claude after:30d select:session' | honed s g aeg --export artifacts/claude
honed s q --json 'harness:claude after:30d select:session' | honed s g workgraph --export artifacts/claude
honed s g q artifacts/claude --info
honed s g q artifacts/claude 'graph:aeg label.startswith:TEST select:node'
honed s g q artifacts/claude 'path:"EDIT -> TEST:fail ->> DONE" outcome:failed select:walk'
honed s g q artifacts/claude 'edge.probability<0.05 edge.count>=3 select:edge'
honed s g q artifacts/claude 'aeg.finding:premature_done workgraph.signal:Stubborn select:session'
honed s g q --json artifacts/claude 'critical:guardrail select:thread' | honed s g decision-trace

A term holds when some element of its level related to the result satisfies it: a node's walks, a walk's nodes and annotations, a session's walks, an event's occurrences. So label:EDIT label:TEST:fail select:walk finds walks with both, and a negated term needs none. A kind prefix (aeg.label:, workgraph.signal:) looks only in graphs of that kind; with select:event, thread or session that joins kinds on shared events. Path patterns use -> (next) and ->> (later), *, A|B, !A, PREFIX*, ^ and $; loop:"A B" with iterations>=N finds repeated cycles; reaches:"A ~> B" follows edges. Numbers compare properties: count>20, edge.probability<0.1, walk.steps>=40. --fields lists everything. Queries warn when sessions an artifact was built from have changed in the index since.

Export and install

session.export("codex") converts a session to another harness's transcript format; session.install("claude") writes a copy that harness can resume or fork. Reflection's handoff uses this to start a reflector from a session's history.