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.

Operator toggle. Gated behind 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.

Retrieval toggle. Chat + this command surface sessions only when 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.

Requires code-session ingest to be enabled. That's an operator setting. If the watcher reports 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

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:

StateMeans
scaffoldedfirst commit created it
wiredit gained its first dependency (got connected in)
testedfirst commit touched its tests
deployedfirst release shipped it

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

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.

Gated + dark. Requires 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.