Get started with Noesis
Run your first observable, governed episode in under five minutes — then start capturing and evaluating every action your agents take.
Overview
Noesis sits between your agents and the real world. Each run is an episode: an append-only, tamper-evident record of what an agent did, what was allowed, and why. This guide walks you through installing Noesis and inspecting your first episode.
Prerequisites
- +Python 3.11 or later
- +The uv package manager (recommended) or pip
- +Any LLM provider keys/endpoints set in your environment — Noesis reads them at runtime
Installation
Install the Noesis CLI and Python package:
# with uv (recommended)
uv add noesis
# or with pip
pip install noesisYour first episode
Run an episode from the CLI. Noesis prints and stores the episode ID and writes artifacts to .noesis/episodes/.
# run a baseline episode
noesis run "hello world"
# list recent episodes
noesis ps --limit 5
# inspect the results
noesis view "$EP_ID"
noesis insight "$EP_ID"Using Python
You can also run and read 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 you can audit, replay, or ship to your own sinks:
.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 payloadsSDKs
Official SDKs ship with batch ingest, sync/async evaluation, retries, and a built-in circuit breaker.
Python
pip install noesis — the full client plus framework callbacks.
TypeScript
npm install @noesis/sdk — typed ingest and policy evaluation.
What's next
Your first policy
Add guardrails that evaluate actions before they execute.
Core concepts
Understand episodes, faculties, and the cognitive loop.
Eval suites
Track correctness, completion, and groundedness over time.
Human-in-the-loop
Route risky decisions to a reviewer and resume in place.
Want a hosted instance?
We're onboarding design partners now.