> ## Documentation Index
> Fetch the complete documentation index at: https://cli-docs.relai.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Trace ingestion

> Ingest folders of agent traces and context into curated RELAI EvalsWiki knowledge.

RELAI reads traces, transcripts, or supporting context, finds durable patterns, and records requirements, risks, and open questions before you decide what to test.

<Warning>
  **Ingestion does not create agent tests.**

  It updates EvalsWiki and stores selected evidence attachments. Create or discover a grounded test afterward.
</Warning>

Run ingestion from an initialized RELAI project with an existing `.relai/evals-wiki/`. If initialization skipped the Wiki, run `relai wiki bootstrap` first.

## Pick the right workflow

| Your evidence | Use |
| - | - |
| A folder of many runs, transcripts, support cases, or mixed context | Trace Ingestion |
| One local run with explicit feedback about what should happen | [Create an agent test from the log](/agent-tests) |
| One behavior you already understand | Create an agent test from a prompt |
| One durable decision from the current conversation | Update or resolve EvalsWiki |

## 1. Ingest traces into EvalsWiki

The source may be outside the repository. Remove secrets and unrelated private data first, then use review mode to inspect ordinary Wiki patches.

<Tabs>
  <Tab title="Ask your coding agent">
    Replace the path and focus, then paste this prompt.

    <Prompt description="Use RELAI to ingest the trace folder at <path> with Wiki review mode. Focus on <goal>. Summarize the proposed requirements, risks, open questions, and selected attachments. Do not create a test yet." actions={["copy"]}>
      Use RELAI to ingest the trace folder at \<path> with Wiki review mode. Focus on \<goal>. Summarize the proposed requirements, risks, open questions, and selected attachments. Do not create a test yet.
    </Prompt>
  </Tab>

  <Tab title="Run in terminal">
    ```sh theme={"system"}
    relai ingest <trace-folder> \
      --review \
      --permissions ask \
      --note "<what to focus on>"
    ```
  </Tab>
</Tabs>

## What RELAI reads and writes

| Item | Behavior |
| - | - |
| Source folder | Read-only; RELAI does not rewrite the original traces |
| Selected excerpts | Copied to `.relai/evals-wiki/attachments/traces/<ingestion-id>/` |
| EvalsWiki | Requirements, risk hypotheses, and open questions may be added or updated |
| Agent tests | Not created by ingestion |

<Note>
  **Review mode is not a zero-write preview.**

  RELAI pauses before ordinary Wiki patches, but selected attachments and risk-hypothesis updates may already be written. Review attachments before committing them.
</Note>

## 2. Create a test from what RELAI learned

First inspect the curated knowledge. Then create one grounded agent test from the highest-impact requirement or risk.

<Tabs>
  <Tab title="Ask your coding agent">
    First, review what RELAI learned.

    <Prompt description="Use RELAI to show what this trace ingestion added to EvalsWiki." actions={["copy"]}>
      Use RELAI to show what this trace ingestion added to EvalsWiki.
    </Prompt>

    Then create grounded coverage.

    <Prompt description="Use RELAI to create one agent test for the highest-impact requirement or risk learned from these traces." actions={["copy"]}>
      Use RELAI to create one agent test for the highest-impact requirement or risk learned from these traces.
    </Prompt>
  </Tab>

  <Tab title="Run in terminal">
    ```sh theme={"system"}
    relai wiki list requirements
    relai wiki list risks
    relai wiki list open-questions

    # Choose one:
    relai wiki list requirements --create-test --id <requirement-id>
    relai test discover --risk <risk-id>
    ```
  </Tab>
</Tabs>

## Resume safely

An ingestion has a one-hour limit per invocation and saves resumable progress on timeout. Resume rechecks the original source folder and preserves review mode. Restart discards only that unfinished session; it does not roll back durable Wiki or attachment writes already made.

<Tabs>
  <Tab title="Ask your coding agent">
    <Prompt description="Use RELAI to inspect and resume the unfinished trace ingestion. Preserve accepted changes and explain anything that still needs my decision." actions={["copy"]}>
      Use RELAI to inspect and resume the unfinished trace ingestion. Preserve accepted changes and explain anything that still needs my decision.
    </Prompt>
  </Tab>

  <Tab title="Run in terminal">
    ```sh theme={"system"}
    relai ingest --resume --permissions ask

    # Prior Wiki and attachment writes remain
    relai ingest <trace-folder> --restart --review --permissions ask
    ```
  </Tab>
</Tabs>

Use `--timeout 2h`, `--timeout off`, or `RELAI_TIMEOUT` when the next invocation needs a different budget. Repeat the override on resume.

<Card title="Ready to evaluate one learned behavior?" href="/agent-tests">
  Create a grounded agent test and simulate the current agent.
</Card>

## Command reference

See [`relai ingest`](/cli/ingest) for all flags, defaults, and recovery details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.