See how your project was built

A hands-on ENGRAM walkthrough · August 2, 2026

Install one tool, point it at a git repo, and turn its history into a living Build Timeline inside ENGRAM — every component moving through scaffolded → wired → tested → deployed, plus a dependency graph, release milestones, feature arcs, and a build-activity heatmap. No setup in the repo, no annotations, no model — it reads what git already knows.

1. Why this tutorial exists

Your coding sessions capture what happened day to day. What they don't capture is the shape of the whole system — which components exist, how far each one has come, what depends on what, and which releases shipped them. That shape is already latent in your repository: git records every commit, tag, and release. The Build Timeline reads that history and reconstructs the story.

It's sourced from git — which is authoritative about what actually shipped — and joined to your ENGRAM session history for the why. Two properties make it trustworthy:

Deterministic. The same repo state always produces the same timeline. No model guesses at your architecture; the component lifecycle is derived from commits, tags, dependency manifests, and CI outcomes by fixed rules.
Zero-touch. Nothing to install in the repo, no config file, no comments to add. You run a tool against a checkout you already have.

Prior tutorials: Tutorial 1 (peer sharing), Tutorial 2 (sub-agents and PATs), Tutorial 3 (keeping memory current), Tutorial 4 (a harness memory). This one stands on its own — no memory concepts required.
Reference: the Coding & Build Timeline chapter in the docs goes deeper on every panel.

2. What you'll produce

One command turns a repo into a timeline you explore in ENGRAM's Coding Sessions tab. It has five parts:

Panel	What it shows
Components	every component your project has, each moving through its lifecycle: `scaffolded → wired → tested → deployed`, on a real timeline
Dependency graph	what's connected to what — derived from your dependency manifests, not guessed
Milestones	your releases (git tags), marked along the top of the timeline
Features	a run of releases grouped into the initiative they delivered — one drillable arc
Build activity	a heatmap of your true development pace, from git commits

Plus gap flags — components that were never deployed, or that have gone dormant — surfaced automatically so nothing quietly falls off the map.

3. Prerequisites

Requirement	Notes
A git repo	any local checkout — the tool reads its history in place and never modifies it
`git` on your PATH	required; `gh` (GitHub CLI) and `cargo` are optional and add richer signals when present
uv	to install and run the tool
An ENGRAM PAT	an `engram_pat_*` token — Settings → API Keys
Build Timeline enabled	your ENGRAM instance needs `BUILD_TIMELINE_ENABLED` on to receive the sync (the tool still produces the timeline locally if it isn't)

Part 1 — Install the tool

The producer is a small, standalone command-line tool called engram-build-timeline. It's pure Python with no heavy dependencies, so it installs in seconds:

uv tool install "engram-build-timeline @ https://pvelua.net/downloads/engram_build_timeline-0.1.1-py3-none-any.whl"

That puts engram-build-timeline (and its short alias engram-bt) on your PATH. Prefer not to install anything? Run it on demand from the same URL:

uvx --from "https://pvelua.net/downloads/engram_build_timeline-0.1.1-py3-none-any.whl" engram-build-timeline --version

Point it at your ENGRAM instance and your token, once per shell:

export ENGRAM_ORCHESTRATOR_URL=https://engram.example.net   # your instance
export ENGRAM_API_KEY=engram_pat_xxxxxxxxxxxxxxxx          # your PAT

Part 2 — Generate and sync your timeline

One command does the whole thing — read the repo, derive the timeline, and sync it into ENGRAM:

engram-build-timeline sync --repo /path/to/your-repo

You'll see it work through the pipeline and print a summary:

▸ repo   /path/to/your-repo
▸ slug   your-org/your-repo
▸ stack  compose
▸ out    ~/.engram/build-timeline/your-org-your-repo
snapshot → …/v5/build_snapshot.json
  48 components (12 top-level, 36 sub)
  9 dependency edges · 27 milestones
  build-state component statuses:
    api-gateway        deployed    [scaffolded → wired → tested → deployed]
    worker             tested      [scaffolded → wired → tested]
    …
synced: {"ok": true, …}

A few things worth knowing about that run:

It figures out your stack. --stack auto (the default) detects a Rust workspace or a docker-compose project from your manifests and derives the dependency graph accordingly. Any other stack still produces components, milestones, and activity — the dependency graph is simply left empty rather than guessed.
It doesn't touch your repo. Intermediate artifacts land in a per-project cache under ~/.engram/build-timeline/, never inside the repo you're analyzing. The real output is the sync into ENGRAM.
Want to look before you sync? Add --dry-run to produce everything locally and skip the upload.

What the lifecycle words mean. Each state is a signal read from git, not a label anyone typed: scaffolded = a component's first commit · wired = it declares its first dependency · tested = its first commit touching a test path · deployed = the first release (a version tag whose CI didn't fail) that shipped one of its commits. Signals that arrive out of order are clamped so the timeline reads cleanly, and the current status is simply the furthest state reached.

Part 3 — Read the timeline in ENGRAM

Open ENGRAM, go to the Coding Sessions tab, and select your project. The Build Timeline panel is now populated. Here's how to read each part.

The Components tab — the lifecycle

Each component is a row, and its lifecycle plays out left to right: a marker for scaffolded, then wired, tested, and deployed as it reached each one, positioned on a real date axis. At a glance you can see which parts of the system are mature (all the way to deployed) and which are still early (scaffolded-only). Hovering a milestone marker along the top shows which release it was.

The Features tab — the initiatives

The Component axis is space and the Milestone axis is release-time — but neither captures an initiative that spanned several releases and touched several components. The Features tab does: it groups a run of releases into the named arc they delivered. Click an arc to drill in and see its releases, the components it touched, and the sessions that built it. A multi-release effort becomes one thing you can point at.

Build activity — your real pace

The Build activity heatmap is driven by git commits, so it reflects your actual development pace rather than only the sessions ENGRAM happened to capture. (A session-driven heatmap sits alongside it as an FYI — sessions often span several days, so the two tell slightly different stories.)

Gap flags — what's dormant or unshipped

Finally, the timeline flags gaps: a component that has never reached deployed, or a service or module that's gone dormant (no recent activity and nothing depending on it). These are the things worth a second look — surfaced for you rather than left to notice by accident.

Part 4 — Keeping it current

The timeline is a snapshot of your repo at the moment you ran sync. To refresh it — after a new release, or once a week — just run the same command again:

engram-build-timeline sync --repo /path/to/your-repo

Re-running is safe and idempotent: components are matched by identity, and state changes supersede rather than overwrite, so each refresh appends the new history without duplicating what was already there. Nothing is lost, and running it twice on an unchanged repo changes nothing.

What this does and doesn't give you

It gives you:

A deterministic, git-sourced view of your system's structure and how it got there — components, lifecycle states, dependencies, releases, features, and activity.
A zero-touch workflow: one tool, any repo, any machine, no repo changes.
Automatic gap detection for unshipped and dormant components.

It doesn't give you:

A guess at architecture. Everything is derived from git; if a signal isn't in your history, it isn't invented.
A dependency graph for every stack. Rust workspaces and docker-compose projects get one today; other stacks still get components, milestones, and activity, with the dependency graph left empty rather than fabricated (more stacks are added on demand).
Anything cloned or written to your repo. ENGRAM reads history; it never modifies the working tree.

Appendix — Gotchas, ranked by how much time they'll cost you

The panel is empty after a successful sync. Your instance likely doesn't have BUILD_TIMELINE_ENABLED turned on, so the sync was accepted-but-ignored (the tool reports a skipped sync in that case). Ask your admin to enable it, then re-run.
No milestones show up. Milestones come from version tags (v1.2.3-style). A repo with no release tags has no milestones — that's expected, and the component lifecycle still works.
The dependency graph is empty. If your repo isn't a Rust workspace or a docker-compose project, dependency edges aren't derived yet. Everything else in the timeline is unaffected.
PRs and CI details are missing. Those come from GitHub via the gh CLI. If gh isn't installed or the repo has no GitHub origin, the tool skips them gracefully and builds the rest from git alone.
You want the artifacts in the repo. By default they live under ~/.engram/build-timeline/. Pass --out .build-timeline to keep them in the repo instead (the Mermaid dependency file renders on GitHub).