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.
CODE_SESSION_INGEST_ENABLED=true
on the orchestrator and the ingest service; a 403 points at the env file when it's off.
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.
CODE_SESSION_RETRIEVAL_ENABLED=true on the orchestrator.
1.3 Installing the ENGRAM Watcher (code-session ingest)
The ENGRAM Watcher is a small standalone CLI that ships your local
Claude Code session logs (~/.claude/projects/**/*.jsonl)
into your ENGRAM KB, so past coding sessions become retrievable from chat and via the
coding-session tools (§1.6). It only decides
"is this session file new or changed?" and streams the bytes upstream — all
parsing, redaction, and graph writes happen server-side. Machines running the watcher
show up under §1.5 Hosts.
403 service disabled, ask whoever runs your ENGRAM
deployment to turn code-session ingest on — until then the watcher runs but uploads are
rejected.
Step 1 · Prerequisites
uv— install withbrew install uvorcurl -LsSf https://astral.sh/uv/install.sh | sh.- Python 3.11+ —
uvfetches a suitable interpreter automatically if you don't have one. There is no upper-version cap; the watcher is a lighthttpx-only client. - A Personal Access Token — mint one under
§1.4 API Keys and copy the
engram_pat_…value.
Step 2 · Install
One command — no repository access required. uv downloads the
wheel and drops a single engram-watcher executable on your $PATH:
uv tool install "engram-watcher @ https://pvelua.net/downloads/engram_watcher-0.2.4-py3-none-any.whl"
Verify with engram-watcher --help. (Prefer pip?
pip install "https://pvelua.net/downloads/engram_watcher-0.2.4-py3-none-any.whl"
works too.) To update to a newer build later, re-run the install with an added
--reinstall flag.
Step 3 · Configure
Only one value is required — your PAT. The server URL is built into the wheel
(https://engram.pvelua.net), so you don't need to set it. Add to your shell
profile (~/.zshrc or equivalent):
export ENGRAM_API_KEY="engram_pat_your_token_here"
# optional — a friendly machine name shown in Settings → Hosts
# export ENGRAM_WATCHER_HOSTNAME="My MacBook"
# optional — only if you point at a non-default deployment
# export ENGRAM_ORCHESTRATOR_URL="https://engram.pvelua.net"
Run source ~/.zshrc (or open a new terminal) so the token reaches the next
invocation.
Step 4 · Run
Three modes:
engram-watcher --backfill # one-shot: ship existing session history
engram-watcher --watch --verbose # live: ship sessions as you code (leave running)
engram-watcher --dry-run # local parse + report only, no upload
A typical first setup is one --backfill to capture history, then
--watch left running in the background for ongoing sessions. The watcher keeps
a small local cursor (~/.engram/code-session-watcher.db) so it never
re-uploads an unchanged file.
Scoping to particular repositories 0.2.1+
By default the watcher captures sessions from every project on the machine. To limit it to the repositories you care about:
engram-watcher --watch --repo trailhead-api --repo trailhead-worker
# or, for a shell profile / launchd job:
export ENGRAM_WATCHER_REPOS="trailhead-api,trailhead-worker"
A short repository name or a full remote URL both work, in any spelling
(git@github.com:you/repo.git, https://github.com/you/repo, or
github.com/you/repo) — they resolve to the same repository. Omit the option
and everything is captured, exactly as before.
Two details worth knowing. A session whose repository can't be determined — a scratch directory with no git remote — is excluded while a filter is set, since it can't be shown to belong to one of your repositories. And a bare short name matches any owner: pass a full URL if you have two repositories with the same name under different accounts.
Running two watchers on one machine — for example one shipping to your main instance and another to a second one — give each its own cursor, or they will consume each other's work:
export WATCHER_CURSOR_DB=~/.engram/code-session-watcher-second.db
Checking what a watcher is actually doing 0.2.2+
On startup the watcher logs its effective configuration in one line, so a misconfiguration is visible immediately rather than after it has captured the wrong work:
watcher_config mode=watch url=https://engram.example.net hostname=My MacBook \
repos=trailhead-api cursor_db=/Users/you/.engram/code-session-watcher-dev.db \
projects=/Users/you/.claude/projects api_key=sha256:f62fa6f7
Two fields repay a glance. repos=(ALL repos) means no filter is set and
every project on the machine will be captured to whichever instance the token
points at. And api_key is a short fingerprint, never the token — enough to
confirm two machines are using two different identities, safe to paste into a bug report.
When a backfill skips a file 0.2.3+
The --backfill summary reports files the repository filter excluded on their own
line, separately from files that were genuinely unchanged since the last run:
Backfill complete:
files_seen: 8
files_posted: 1
files_skipped_unchanged: 6
files_skipped_repo: 1
files_failed: 0
Each exclusion is logged as backfill_skipped_repo. If it shows
repo_url=(unresolved), the watcher could not tell which repository the
session belongs to, so a --repo filter left it out. Earlier versions
counted these as "unchanged", so a skipped session looked identical to one that was
already captured. 0.2.3 also reads further into each transcript to find its working
directory. Newer Claude Code sessions open with a long run of metadata before the first
event that records it, and 0.2.2 stopped looking after 20 lines.
Long sessions in a backfill 0.2.4+
A --backfill posts each transcript whole, and ENGRAM reads it, extracts its
entities and writes the graph before answering. For a very long session that took more than
ten minutes, so the post was cut off and the file counted as files_failed (nothing
was lost; the next backfill retried it, and failed the same way).
From 0.2.4 the watcher asks ENGRAM to take each transcript as a job, then checks on it every
ten seconds until it finishes, logging ingest_job_waiting while it waits. A
long session now takes as long as it takes, up to four hours, and a server restart in the
meantime doesn't count against it. The summary is the same as before. Watch mode is unchanged:
it sends small pieces as a session grows.
Step 5 · Verify
After your next non-trivial Claude Code session settles, open Settings → Hosts (§1.5) — your machine appears as a new host row — and the session itself shows up under the Coding Sessions tab. Set a friendly host label if you like; it propagates everywhere that session is shown.
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 sessnext to a component = captured sessions that touched it; click to list them, click one to open it.⚠ gapsflags 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 standalone tool, engram-build-timeline, that
reads a repo's git history and syncs the result. It's idempotent and safe to
re-run on every release. Install it once:
uv tool install "engram-build-timeline @ https://pvelua.net/downloads/engram_build_timeline-0.1.1-py3-none-any.whl"
Point it at your ENGRAM instance and a repo:
export ENGRAM_ORCHESTRATOR_URL=https://engram.pvelua.net
export ENGRAM_API_KEY=engram_pat_... # a PAT for the sessions' owner
engram-build-timeline sync --repo /path/to/your-repo
It's git-sourced, so the result is the same from any current clone, and the session evidence
joins server-side across every machine's captured sessions — one run captures everything. The
dependency stack is auto-detected (--stack auto); add
--dry-run to produce the files locally without syncing. The sync needs
Build Timeline enabled on your instance — otherwise it reports a skipped sync
and still writes the files locally.
Step-by-step walkthrough: Tutorial 5 — generate a Build Timeline from any repo.
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.
SESSION_CAPTURE_ENABLED (a 404 means it's
off). Re-running with the same session_id is idempotent; the capture adds the sha
+ summary while the Watcher supplies the full action list.