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

# Trajectory Database

> How trajectories, embeddings, and curation metadata are stored

## Python Database

`TrajectoryDatabase` persists to disk at `db_path`:

* `trajectories/*.json`
* `index.faiss`
* `index_ids.json`
* `curation.json`
* `embedder.json`

Key points:

* stores trajectories and step-level examples
* searches with FAISS cosine similarity (normalized embeddings)
* tracks curation metadata per trajectory
* supports deferred validation and deprecation/supersession metadata

## TypeScript Database

TypeScript `TrajectoryDatabase` uses a `StorageAdapter` interface.

Built-in adapter:

* `FileSystemAdapter` (JSON-backed, cosine search in adapter)

Web example adapter:

* `ConvexAdapter` (in `web-example/src/lib/convex-adapter.ts`)

## Search Surfaces

* Trajectory-level: `search(query, k)`
* Step-level: `search_steps(...)` in Python and `searchSteps(...)` in TypeScript

ReAct retrieval primarily uses step-level search.