Quickstart

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

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

Installation

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

From source (recommended)
uv (when PyPI is live)
pip (when PyPI is live)

git clone https://github.com/saraeloop/noesis.git
cd noesis
uv tool install .
# or: pipx install .

uv add noesis

pip install noesis

Run your first episode

Run a baseline episode

Execute a simple episode using the CLI:

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.

List recent episodes

View your episodes in a table:

noesis ps --limit 5

Add -j for JSON output when scripting:

noesis ps -j | jq '.episodes[0]'

Inspect the results

View the episode dashboard and insight metrics:

noesis view "$EP_ID"
noesis insight "$EP_ID"

Using Python

You can also run episodes programmatically:

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).

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").

What’s next?

Your first episode

A deeper walkthrough of running and inspecting episodes.

Your first policy

Learn how to add guardrails with intuition policies.

Core concepts

Understand episodes, faculties, and the cognitive loop.

Python API

Explore the full API reference.

Get started

Tutorials

How-to guides

Explanation

Prerequisites

Installation

Run your first episode

Using Python

Inspect artifacts

What’s next?

Your first episode

Your first policy

Core concepts

Python API

​Prerequisites

​Installation

​Run your first episode

​Using Python

​Inspect artifacts

​What’s next?

Your first episode

Your first policy

Core concepts

Python API

Prerequisites

Installation

Run your first episode

Using Python

Inspect artifacts

What’s next?