Internals

This page documents the internal mechanisms behind Metateam's session capture, context loading, and related systems. It is reference material for debugging, integration, and understanding how the system works under the hood.

For the user-facing explanation of these concepts, see Concepts.

Session Capture

SessionStart Hook

When an AI client starts a session in a directory where Metateam is active, the SessionStart hook fires. It:

  1. Checks for .nometateam markers and skips blocked paths (node_modules, .git, vendor, etc.).
  2. Signals client readiness via METATEAM_CREW_READY_FILE (used by summon to detect when the agent is up).
  3. Re-registers the crew agent if persona/crew env is set — handles client-side resets that start a fresh session without a fresh summon.
  4. Emits a session_start log event for observability.

The hook does not inject context. For managed summons, Metateam prepares context before launch by calling the same loader as metateam start and writing START.md beside the generated instruction file; the persona reads that file.

SessionEnd Hook

Current builds treat the internal SessionEnd command as a no-op compatibility shim so stale installed configs do not error. Upload is communicator-driven for crew sessions. Explicit catch-up is available through metateam session upload.

The upload path reads the transcript from the client's local storage, converts it to markdown, applies size compaction when needed, detects resume chains, and uploads in the background. Compaction is size reduction, not redaction. Secrets are not removed.

Client Integration

Client Hook mechanism Context loading
Claude Code Native SessionStart hook for crew re-register / readiness; upload is communicator-driven summon writes START.md; persona reads it
Gemini CLI Native SessionStart hook for crew re-register / readiness; upload is communicator-driven summon writes START.md; persona reads it
Codex CLI No native hook parity; managed crew upload is communicator-driven, with explicit metateam session upload catch-up summon writes START.md; persona reads it
Pi Managed crew upload is communicator-driven; explicit upload is available summon writes AGENTS.md and START.md; persona reads them
OpenCode Managed crew upload reads the native session database; explicit upload is available summon writes AGENTS.md and START.md; persona reads them
Grok Claude-compatible readiness hooks where configured; managed crew upload reads the native updates stream and sidecars summon writes AGENTS.md and START.md; a short launch prelude explicitly tells Grok to read both

Resume Chains

When an agent resumes a session, the client creates a new transcript linked to the parent. Metateam follows this chain to find the root session ID, so all continuations are stored under one record.

Context Loading (START.md / metateam start)

What Gets Loaded

When summon prepares START.md (or when metateam start is run manually), the API returns:

  • Important KB entries — full content of entries marked as important, and all entries in compartments marked as important. These appear first.
  • KB structure index — compartment and entry names (without content) for non-important entries. This lets the agent know what knowledge exists and request it with metateam kb <path> if needed.
  • Relevant session summaries — sessions matching the current context (same project, same directory, relevant to the first prompt). Ranked using BM25 full-text search.

Ignored Paths

Metateam skips context detection and uploads for certain paths: node_modules, .git, vendor, venv, target, dist, build, __pycache__, and similar. This prevents supply-chain context loading from malicious packages and avoids noise.

Manual Session Upload

metateam session upload is the explicit catch-up/debug path for transcripts that were not uploaded automatically by the communicator-driven crew path. It can upload from known client transcript locations or from a specific transcript file.

This is best-effort. It depends on transcript file discovery, readable local files, and the client transcript format remaining compatible.

Grok sessions are discovered under METATEAM_GROK_ROOT, $GROK_HOME/sessions, or ~/.grok/sessions in that order. Only updates.jsonl is treated as the conversation; summary.json supplies session ID and cwd, while signals.json supplies model/context counts. Missing cwd fails closed for upload.

KB Versioning

Every KB edit creates a new immutable version. History can be viewed with metateam kb log <path>, versions diffed with metateam kb diff <path>, and any previous version restored with metateam kb rollback <path>.

Data Flow

Summon requested
    │
    ▼
Metateam prepares `START.md`
    │ collects: working directory, git metadata, KB context, crew identity
    │ calls API for context
    │ receives: session summaries + important KB entries
    │ writes the formatted context beside the generated instruction file
    ▼
Agent client starts
    │
    ▼
SessionStart hook fires
    │ signals client readiness (METATEAM_CREW_READY_FILE)
    │ re-registers crew agent (handles /clear)
    │ emits session_start log event
    ▼
Agent reads `START.md` and works normally
    │ client writes transcript
    ▼
Agent session ends or session changes
    │
    ▼
Communicator upload path or explicit session upload runs
    │ reads transcript, converts to markdown
    │ detects resume chains, compacts if needed
    │ uploads to API
    ▼
Session stored
    │ available to future `START.md`/`metateam start` context loads
    │ searchable via metateam session search
    ▼
Next session starts → cycle repeats

See Also