Coding & Build Timeline

ENGRAM sits alongside your coding agents. It captures your sessions, then turns their history into a Build Timeline — a living map of what's been built, how it got there, what's connected, and what's dormant.

1. Coding sessions

When you work with Claude Code (or another agent), ENGRAM can persist each session as :CodeSession + :CodeRecap + :CodeAction nodes in your graph — the summary, the actions, and the entities — so it's retrievable later by topic and participates in the same associative retrieval as your articles and chat. Sessions arrive either automatically (the Watcher) or on demand (the commands below and the capture skill).

1.1 /ingest-code-session

Persist a Claude Code session's JSONL transcript into the graph so it becomes retrievable later. The session UUID is the JSONL filename under ~/.claude/projects/<encoded-project>/ — pass it as the command argument.

1.2 /find-in-engram-code

The "what did I do before" recall surface — sibling to /find-in-engram-kb but over your past coding sessions instead of articles. PPR ranks :CodeSession nodes by entity proximity to your query, aggregating mass through their :CodeRecap and :CodeAction children. Use it to recall prior coding context, file edits, or decisions from an earlier session.

2. The Build Timeline

Sessions are episodes; the Build Timeline is the shape they add up to. Open Coding Sessions → a project → Build Timeline. It's sourced from git — authoritative about what actually shipped — joined to your session history for the why. It answers: what have we built, when did it ship, what's connected, what's dormant, and which sessions did the work.

2.1 The Components tab — the lifecycle

One row per top-level component (service, UI surface, module, infra…), each a bar on a shared time axis showing the states it reached, from git:

State	Means
scaffolded	first commit created it
wired	it gained its first dependency (got connected in)
tested	first commit touched its tests
deployed	first release shipped it

• A thin coloured marker sits at the date each state was first reached, so a state reached the same day as the next is still visible.
• A missing phase means "no signal in git," not "skipped." A component nothing depends on has no wired (e.g. shared libraries — everything depends on them).
• Hover the release-tick strip above the rows — a callout names the nearest release (tag · title · date). No aiming at a hairline.
• ◇ N sess next to a component = captured sessions that touched it; click to list them, click one to open it.
• ⚠ gaps flags components that are dormant/orphan (no dependencies, long untouched) or undeployed (started, never shipped), with the reason inline.

2.2 The Features tab — the initiatives

One arc per initiative — a named body of work spanning several releases. Each shows its status (active/shipped), release count, components touched, and sessions. Click a feature (chevron ▸) to drill in: its releases, the components it moved, and the sessions that built it. This is how you see e.g. a memory-fact-update project as one arc — its releases, components, and the sessions behind them — instead of scattered across the version list.

2.3 Build activity vs. session activity

Below the panel: Build activity (primary) is a heatmap of git commits per day — the true development pace, complete regardless of capture. The Session activity heatmap beside it (FYI) shows what ENGRAM captured; a session can span several days, so its count isn't a per-day activity measure.

2.4 Generating a project's timeline

The timeline is produced by a small script that reads git and syncs the result. It's idempotent and safe to re-run on every release. From the repo root:

export ENGRAM_ORCHESTRATOR_URL=https://engram.pvelua.net
export ENGRAM_API_KEY=engram_pat_...        # a PAT for the sessions' owner

git pull --ff-only
bash /path/to/engram-personal-kb/scripts/build_timeline/run.sh

It's git-sourced, so the result is the same on any machine (run from whichever clone is current), and the session evidence joins server-side from every machine's captured sessions — one run captures everything. For a Rust workspace, prefix BUILD_TIMELINE_STACK=cargo. Needs BUILD_TIMELINE_ENABLED on (otherwise it just writes the files locally). See the extraction runbook for details.

3. Capturing a session from inside it

The Watcher captures sessions passively, by reading Claude Code's transcript files after the fact. The capture skill is the active, harness-neutral counterpart: from inside a live session you gather the ground truth — the git HEAD, the files you touched, and a short distilled summary of what you built — and hand it to ENGRAM. It writes a session that converges on the Watcher's node, so it's additive, and it lands the two signals a quiet transcript loses: touched files (component evidence) and the HEAD sha (commit evidence).

3.1 When to use it

• End of a work session or after a milestone — a deliberate "what we built" record.
• Especially where the Watcher is blind: Cowork, Claude Desktop with a shell, other coding agents.

3.2 How to run it

Slash command (Claude Code): /capture-session <session_id> — the agent gathers git state, writes the summary, and captures.

MCP tool (any connected agent): gather with a shell, then call capture_session with session_id, your summary, head_sha, touched, repo_url.

Script (no MCP): with ENGRAM_ORCHESTRATOR_URL + ENGRAM_API_KEY set,

bash .claude/skills/capture-session/capture.sh "<session_id>" "<your summary>"

Deeper operator detail lives in the runbooks: docs/runbooks/BUILD_TIMELINE_EXTRACTION.md, BUILD_TIMELINE_USING.md, and SESSION_CAPTURE.md.