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

​
Prerequisites

  • Python 3.12 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:

​
Run your first episode

1

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

List recent episodes

View your episodes in a table:
noesis list --limit 5
Add -j for JSON output when scripting.
3

Inspect the results

View the episode summary and insight metrics:
noesis show "$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.