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 /clear, which fires SessionEnd → SessionStart without a fresh summon.
  4. Emits a session_start log event for observability.

The hook does not inject context. Context loading is the agent's responsibility, via metateam start, which every persona invokes as part of its startup sequence.

SessionEnd Hook

When a session ends, the SessionEnd hook:

  1. Reads the transcript from the client's local storage.
  2. Converts it to markdown — a significant size reduction.
  3. Applies compaction if the markdown exceeds 10 MB. Compaction is size reduction, not redaction. Secrets are not removed.
  4. Detects resume chains — if this session resumed a previous one, the upload uses the original session's ID so continuations merge into one record.
  5. Spawns a detached background process to upload and exits immediately.

Client Integration

Client Hook mechanism Context loading
Claude Code Native hooks (SessionStart for crew re-register / readiness; SessionEnd for transcript upload) metateam start invoked by the persona
Gemini CLI Native hooks (SessionStart for crew re-register / readiness; SessionEnd for transcript upload) metateam start invoked by the persona
Codex CLI Background monitor polls for agent processes and scans for transcripts metateam start invoked by the persona

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 (metateam start)

What Gets Loaded

When the agent runs metateam start, 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.

Background Monitor

The monitor (metateam monitor) is a background process for clients without native hook support:

  1. Polls for running agent processes at regular intervals.
  2. When a process is detected, opens a time window.
  3. When the process exits, scans the transcript directory for files modified during that window.
  4. Uploads new transcripts in the background.

This is best-effort. It depends on process detection, transcript file discovery, and the transcript being complete when the process exits.

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

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 runs `metateam start [--as <id>]`
    │ collects: working directory, git metadata, KB context
    │ calls API for context
    │ receives: session summaries + important KB entries
    │ outputs the formatted context to stdout for inclusion in the agent's prompt
    ▼
Agent works normally
    │ client writes transcript
    ▼
Agent session ends
    │
    ▼
SessionEnd hook fires
    │ spawns detached background process
    │ reads transcript, converts to markdown
    │ detects resume chains, compacts if needed
    │ uploads to API
    ▼
Session stored
    │ available to future `metateam start` calls
    │ searchable via metateam session search
    ▼
Next session starts → cycle repeats

See Also