docs
Persistence & Memory
Ninetrix saves agent state as checkpoints automatically via the telemetry API. Every tool call, LLM response, and token count is recorded with no database config required.
Zero config
Set
AGENTFILE_API_URL and AGENTFILE_RUNNER_TOKEN — that is all. Checkpoints are posted to the API automatically on every turn. Run ninetrix dev to start the local stack.Resume a session
Thread IDs are user-defined strings. Any run with the same thread ID fetches the prior checkpoint from the API on startup and continues from where it left off:
Bash
# First run — starts fresh
ninetrix run --thread-id project-alpha
# Second run — resumes from where it left off
ninetrix run --thread-id project-alpha
What gets stored
| Field | Description |
|---|---|
thread_id | User-defined session identifier |
trace_id | Unique ID per run (auto-generated) |
parent_trace_id | Set when this run was triggered by another agent |
agent_id | Agent name from agentfile.yaml |
step_index | Turn counter within the run |
status | in_progress | completed | error | waiting_for_approval | budget_exceeded |
history | Full message history (user, assistant, tool_use, tool_result) |
history_meta | Parallel list with timestamps and token counts per message |
tokens_used | Total tokens this turn |
model | Model ID used |
View checkpoints
Bash
ninetrix trace --thread-id project-alpha # render the full run tree
Or open the dashboard at http://localhost:8000/dashboard and click on any thread.
Durable Runs
Durable Runs are enabled automatically (execution.durability: true). If the agent container crashes — OOM, SIGKILL, network drop — Docker restarts it and the agent fetches the prior checkpoint from the API, repairs any partial turn, and resumes with no user action required. See Durable Runs for the full explanation.
Zero-config crash recovery
Durable Runs work automatically as long as
AGENTFILE_API_URL and AGENTFILE_RUNNER_TOKEN are set.