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

If you’re trying Noēsis while it’s still pre-release, start with From source (preferred). 
git clone https://github.com/saraeloop/noesis.git
cd noesis
uv tool install .
# or: pipx install .
Source-first is recommended while the PyPI release is pending.

​
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_abc123) and creates artifacts in the ./runs 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 ./runs by default, relative to where you run the command): 
runs/
  demo/                    # label (configurable)
    ep_abc123/             # episode id
      summary.json         # metrics, outcome, cross-links
      state.json           # current plan and episode state
      events.jsonl         # timeline with causal IDs
      manifest.json        # SHA-256 + size ledger
      learn.jsonl          # optional learning payloads
Use jq for pretty-printing JSON artifacts: cat runs/demo/ep_abc123/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.