Context Intelligence Session Navigation

This skill covers navigation of flat JSONL session files written by the LoggingHandler. These files are the universal baseline — always present regardless of whether graph stores are configured. Use shell tools (jq, grep, wc, head) to extract data safely.

For the complete event-by-event field reference, see context/event-schema.md. For ready-to-use jq/grep recipes, see context/safe-extraction-patterns.md.

Disk Layout

Resolve the root once before any discovery:

CONTEXT_INTELLIGENCE_ROOT="${AMPLIFIER_CONTEXT_INTELLIGENCE_BASE_PATH:-$HOME/.amplifier/projects}"

$CONTEXT_INTELLIGENCE_ROOT/{project-slug}/sessions/{session_id}/context-intelligence/
├── events.jsonl      # one JSON object per line, append-only
└── metadata.json     # session metadata, written on start, updated on end

• $CONTEXT_INTELLIGENCE_ROOT — resolved from the idiom "${AMPLIFIER_CONTEXT_INTELLIGENCE_BASE_PATH:-$HOME/.amplifier/projects}" (unset → legacy default). Relocation is reader-visible ONLY via this env var. The hook's config.base_path moves where the writer stores captures, but readers (this skill, discover.py, the recipe) resolve the root solely from the env var — so always relocate via AMPLIFIER_CONTEXT_INTELLIGENCE_BASE_PATH, not config.base_path alone, or readers will look in the wrong place.
• {project-slug} — derived from the full working directory path (see Project Slug Algorithm below)
• {session_id} — unique session identifier (UUID or UUID with agent suffix for child sessions)
• context-intelligence/ — subdirectory containing the session data files
• events.jsonl — append-only log of every event the kernel emits during the session
• metadata.json — compact session metadata for quick lookup without parsing the full event log

Example paths (with root resolved):

$CONTEXT_INTELLIGENCE_ROOT/-home-user-myapp/sessions/55c8841a-1234-5678-9abc-def012345678/context-intelligence/events.jsonl
$CONTEXT_INTELLIGENCE_ROOT/-home-user-myapp/sessions/55c8841a-1234-5678-9abc-def012345678/context-intelligence/metadata.json

⚠ MARKER RULE — the defect this prevents: Every discovery glob MUST include the context-intelligence/ path segment and MUST NOT stop at sessions/<id>/:

CORRECT:  "$CONTEXT_INTELLIGENCE_ROOT"/*/sessions/*/context-intelligence/events.jsonl
WRONG:    "$CONTEXT_INTELLIGENCE_ROOT"/*/sessions/*/metadata.json   # catches Amplifier core's files

Why: Amplifier core writes sessions/<id>/metadata.json with NO context-intelligence/ segment. Globbing one level too shallow latches onto core's files and produces a confident wrong count.

Canonical marker = events.jsonl. The Python readers (discover.py, the workflow recipe) treat context-intelligence/events.jsonl as the single discriminator of a real capture. metadata.json is used here only to read fields (workspace, status, …); both files are written together, so either glob includes the context-intelligence/ segment and avoids the false-positive. When you need a strict capture count that matches the code, glob events.jsonl, not metadata.json.

⚠ FAIL-LOUD RULE: When zero captures are found, say exactly "looked in <root>, found 0" — never report a confident count from a shallower glob, never silently fall back to a different path.

Record Format

Each line in events.jsonl is a single JSON object with exactly four fields, always in this order:

{"event":"tool:pre","workspace":"my-project","timestamp":"2026-03-10T11:13:09.792+00:00","data":{...}}

Key principle: No field promotion, no level classification, no payload mutation. What the kernel emits is exactly what gets stored in data. The workspace field is the only addition the hook makes — it is injected at write time from ConfigResolver.workspace.

metadata.json

Written on session:start or session:fork, updated on session:end.

Required Fields (always present)

Optional Fields (omitted when absent — no nulls)

Optional fields are omitted entirely when absent — no null values, compact JSON.

Example (minimal root session):

{"format":"context-intelligence","version":"1.0.0","session_id":"55c8841a-...","workspace":"my-project","parent_id":"","started_at":"2026-03-10T11:13:09.000+00:00","status":"running","working_dir":"/home/user/myapp"}

Example (child session with optional fields):

{"format":"context-intelligence","version":"1.0.0","session_id":"55c8841a-...-foundation:explorer","workspace":"my-project","parent_id":"1cb9e5f5-...","started_at":"2026-03-10T11:13:09.000+00:00","status":"completed","ended_at":"2026-03-10T11:15:42.000+00:00","working_dir":"/home/user/myapp","agent_name":"foundation:explorer","recipe_name":"code-review","recipe_step":"analyze"}

Workspace and Project Slug

Workspace scopes all event data. It is written into every events.jsonl line and metadata.json. Two concepts work together:

By default workspace equals project_slug (both derived from the working directory). They can differ when workspace is set explicitly via settings.yaml or env var — for example, workspace "my-api" while project_slug is "-home-user-myapp".

Consequence for navigation:

• Directory-first lookup — when workspace matches the project_slug, all sessions for that workspace live under $CONTEXT_INTELLIGENCE_ROOT/{workspace}/sessions/. This is fast and the common case.
• Field-based filtering — when workspace was set explicitly (overriding the slug default), scan across all project directories and filter records by jq 'select(.workspace == "TARGET")'.

Always check both: attempt directory lookup first, then fall back to cross-project field scan.

Project Slug Algorithm

The project slug is derived from the full absolute path of the working directory:

1. Take the resolved absolute path of working_dir
2. Replace every / with - and every \ with -
3. Remove : (Windows drive letters)
4. If the result does not start with -, prepend -
5. Use "default" if the result is empty

Examples:

Note: the slug encodes the full path, not just the basename. /home/alice/myapp and /home/bob/myapp get different slugs: -home-alice-myapp and -home-bob-myapp.

Safe Extraction Discipline

Session event files can contain lines with 100k+ tokens (e.g., llm:response with full model output). Four golden rules protect against context overflow:

1. Never cat an events.jsonl file. A single line can be larger than your entire context window. Always use targeted extraction.
2. Use jq -c for structured queries. The -c flag keeps output compact (one line per result). Always filter to specific fields rather than dumping entire records.
3. Use grep -n | cut for line-targeted extraction. First find matching line numbers with grep -n, then extract specific lines with sed or head/tail. Never pipe raw grep output of event data into your context.
4. Preview with wc -l and head before extracting. Always check file size and peek at the first few lines before running any extraction. This prevents accidentally pulling in massive files.

Common Navigation Patterns

Resolve the root once before all discovery snippets in this section:

CONTEXT_INTELLIGENCE_ROOT="${AMPLIFIER_CONTEXT_INTELLIGENCE_BASE_PATH:-$HOME/.amplifier/projects}"

Resolve workspace to a project directory

# If workspace == project_slug (common default), sessions are here:
ls "$CONTEXT_INTELLIGENCE_ROOT"/{workspace}/sessions/

# If workspace was set explicitly and differs from project_slug,
# find all directories containing sessions tagged with this workspace:
grep -rl '"workspace":"{workspace}"' "$CONTEXT_INTELLIGENCE_ROOT"/*/sessions/*/context-intelligence/metadata.json \
  | sed 's|/context-intelligence/metadata.json||'

List all sessions for a workspace

# Fast path: workspace matches directory name (default case)
for ev in "$CONTEXT_INTELLIGENCE_ROOT"/my-project/sessions/*/context-intelligence/events.jsonl; do
  f="${ev%/events.jsonl}/metadata.json"   # canonical marker = events.jsonl; fields from sibling
  jq -r '[.session_id, .status, .started_at, .agent_name // "(root)"] | join("\t")' "$f" 2>/dev/null
done | sort -t$'\t' -k3

# Scoped path: workspace set explicitly — scan all projects, filter by field
for ev in "$CONTEXT_INTELLIGENCE_ROOT"/*/sessions/*/context-intelligence/events.jsonl; do
  f="${ev%/events.jsonl}/metadata.json"   # canonical marker = events.jsonl; fields from sibling
  jq -r 'select(.workspace == "my-project") | [.session_id, .status, .started_at, .agent_name // "(root)"] | join("\t")' "$f" 2>/dev/null
done | sort -t$'\t' -k3

Check what workspace a session belongs to

jq -r '.workspace' metadata.json
# or from events.jsonl (first line only — safe):
head -1 events.jsonl | jq -r '.workspace'

Filter events by workspace across a project

# Count events per workspace across all sessions in a project directory:
jq -r '.workspace' "$CONTEXT_INTELLIGENCE_ROOT"/-home-user-myapp/sessions/*/context-intelligence/events.jsonl \
  | sort | uniq -c | sort -rn

Find sessions by status within a workspace

# Within a single project directory:
for ev in "$CONTEXT_INTELLIGENCE_ROOT"/my-project/sessions/*/context-intelligence/events.jsonl; do
  f="${ev%/events.jsonl}/metadata.json"   # canonical marker = events.jsonl; fields from sibling
  jq -r 'select(.status == "running") | .session_id' "$f" 2>/dev/null
done

# Cross-project, scoped to workspace:
for ev in "$CONTEXT_INTELLIGENCE_ROOT"/*/sessions/*/context-intelligence/events.jsonl; do
  f="${ev%/events.jsonl}/metadata.json"   # canonical marker = events.jsonl; fields from sibling
  jq -r 'select(.workspace == "my-project" and .status == "running") | .session_id' "$f" 2>/dev/null
done

Event summary for a session

# Count total events
wc -l < events.jsonl

# Count events by type
jq -c '.event' events.jsonl | sort | uniq -c | sort -rn

Find errors in a session

# Find error event line numbers only (never output the full lines)
grep -n '"event":"orchestrator:error"\|"event":"tool:error"' events.jsonl | cut -d: -f1

Extract a specific event by line number

sed -n '42p' events.jsonl | jq -c '{event, workspace, ts: .timestamp}'

Count events by type in a session

grep -c '"event":"tool:pre"' events.jsonl

Event Name Taxonomy

All events follow the {namespace}:{action} naming convention:

For the complete field reference for each event, see context/event-schema.md.