> ## Documentation Index
> Fetch the complete documentation index at: https://noesis-32c1d602-cursor-technical-documentation-improvements.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get your first Noēsis episode running in under 5 minutes.

This guide walks you through installing Noēsis and running your first observable episode.

## Prerequisites

* Python 3.11 or later
* `uv` package manager (recommended) or `pip`

<Warning>
  Before running commands, set any LLM adapter or model provider environment variables (keys, endpoints). Noēsis reads them at runtime.
</Warning>

## Installation

The PyPI release is pending. For now, install from source:

<Tabs>
  <Tab title="From source (recommended)">
    ```bash theme={null}
    git clone https://github.com/saraeloop/noesis.git
    cd noesis
    uv tool install .
    # or: pipx install .
    ```
  </Tab>

  <Tab title="uv (when PyPI is live)">
    ```bash theme={null}
    uv add noesis
    ```
  </Tab>

  <Tab title="pip (when PyPI is live)">
    ```bash theme={null}
    pip install noesis
    ```
  </Tab>
</Tabs>

## Run your first episode

<Steps>
  <Step title="Run a baseline episode">
    Execute a simple episode using the CLI:

    ```bash theme={null}
    noesis run "hello world" 
    ```

    This prints and stores the episode ID (for example, `ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C`) and creates artifacts in the `.noesis/episodes/` directory, relative to where you run the command.
  </Step>

  <Step title="List recent episodes">
    View your episodes in a table:

    ```bash theme={null}
    noesis ps --limit 5
    ```

    Add `-j` for JSON output when scripting:

    ```bash theme={null}
    noesis ps -j | jq '.episodes[0]'
    ```
  </Step>

  <Step title="Inspect the results">
    View the episode dashboard and insight metrics:

    ```bash theme={null}
    noesis view "$EP_ID"
    noesis insight "$EP_ID"
    ```
  </Step>
</Steps>

## Using Python

You can also run episodes programmatically:

```python theme={null}
import noesis as ns

# Run an episode
episode_id = ns.run("Draft a weekly engineering update", intuition=True)

# Read the summary
summary = ns.summary.read(episode_id)
print(f"Success: {summary['metrics']['success']}")

# Read the event timeline
events = list(ns.events.read(episode_id))
for event in events:
    print(f"{event['phase']}: {event.get('payload', {})}")
```

## Inspect artifacts

Every episode creates a structured artifact directory (written under `.noesis/episodes/` by default, relative to where you run the command):

```
.noesis/episodes/
  ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C/   # episode id (ULID)
    summary.json                  # metrics + rollups
    state.json                    # final state snapshot
    events.jsonl                  # append-only timeline
    manifest.json                 # SHA-256 + size ledger
    learn.jsonl                   # optional learning payloads
  _episodes/                      # optional episode index (best-effort)
    episodes.jsonl
```

The `_episodes/` index is written on a best-effort basis at the end of runs and may be missing or empty (for example, if indexing fails due to permissions).

<Tip>
  Use `jq` for pretty-printing JSON artifacts: `cat .noesis/episodes/ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C/summary.json | jq .`

  To change the artifact location, set `NOESIS_RUNS_DIR` or in Python call `ns.set(runs_dir="./my-runs")`.
</Tip>

## What's next?

<CardGroup cols={2}>
  <Card title="Your first episode" icon="play" href="/tutorials/first-episode">
    A deeper walkthrough of running and inspecting episodes.
  </Card>

  <Card title="Your first policy" icon="shield" href="/tutorials/first-policy">
    Learn how to add guardrails with intuition policies.
  </Card>

  <Card title="Core concepts" icon="lightbulb" href="/explanation/core-concepts">
    Understand episodes, faculties, and the cognitive loop.
  </Card>

  <Card title="Python API" icon="code" href="/reference/python-api">
    Explore the full API reference.
  </Card>
</CardGroup>