Internals

This page documents the internal mechanisms behind Metateam's session capture, context injection, 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. Collects local context: working directory, git branch, recent commits, git status, and project pin file if present.
  3. Calls the API with this context.
  4. Injects the API response into the agent's session as additional context.

What gets sent to the API: working directory, hostname, OS, CLI version, agent type, git metadata (repo root, branch, remote, recent commits, status).

What comes back: a formatted string containing session summaries, important KB entries, and a KB structure index (compartment and entry names without content for non-important entries).

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
Claude Code Native hooks (SessionStart/SessionEnd in Claude settings)
Gemini CLI Native hooks (SessionStart/SessionEnd in Gemini settings)
Codex CLI Background monitor polls for agent processes and scans for transcripts

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 Injection

What Gets Injected

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 injection 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
    │ collects: working directory, git metadata, KB context
    │ calls API for context
    │ receives: session summaries + important KB entries
    │ injects: additional context into agent session
    ▼
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 for future context injection
    │ searchable via metateam session search
    ▼
Next session starts → cycle repeats

See Also