An AI agent that knows why it acted, and whether it worked

Nous records each decision with its reasons and confidence, then grades it against what happened. What worked becomes a procedure. A failure can become a censor, a learned “don't do this” rule that blocks the action in code.

Open source under Apache-2.0. Self-hosted, on PostgreSQL 17. Version 1.2.0.

The Nous dashboard's decision browser with one decision open: deploy the flaky-test fix to staging after owner approval, process, medium stakes, confidence 85%, outcome success, with its context and three reasons (constraint, empirical, analysis). Below it, six more decisions with their confidence and outcome: success, pending, partial and failure.
Sample data The decision browser in the Nous dashboard. Every decision keeps its reasons, its confidence and, later, its outcome.

A record of why, for every turn

Open any conversation and read it turn by turn: the frame Nous chose (the kind of situation it took the turn to be, such as a task or a debugging session) and the reason it chose it, what the critic, a second check on that choice, said, and the reason the model gave for each tool call. Refused, gated and failed calls are on the record too.

Each turn also shows its claim check: what Nous said it did, matched against the calls that ran. Recording is opt-in (NOUS_TOOL_CALL_LOG_ENABLED, plus NOUS_TOOL_REASON_ENABLED for the tool-call reasons), and turns are kept for 30 days.

See the dashboard
Turn 3 of a session in the Nous Work view. The frame changed from task to decision, chosen by the critic, which overrode the default and says why: the request has effects outside the repo. Three tool calls follow, each with the reason the model gave: record_decision to record the choice with confidence and reasons; bash to deploy to staging, gated by the action gate because a staging deploy needs the owner's approval; and dag_create to turn the deploy into a workflow with an approval step. The reply says an approval card went to the companion, and the claim check passed.
Sample data A session trace in the Work view: the critic moved this turn to the decision frame and says why; each tool call carries the model's reason, and the deploy was gated.

What Nous does that an agent with memory does not. Each one is in the code you clone.

Keeps the reasons, then grades the result

Each significant decision is saved with its confidence and several independent reasons. Later it is reviewed against the outcome, and Brier scores (the average squared gap between confidence and outcome; lower is better) show whether its confidence was right.

Learns from what worked

Clusters of good decisions, lessons from episodes (summaries of past conversations) and error recoveries become procedures, each through a lesson gate that wants cited evidence. Weak procedures are revised or retired. A correction becomes a stored principle.

Turns failures into rules that hold

When Nous finds a failure mode it can create a censor: a rule that blocks the matching action before it runs. Censors and CEL guardrails (conditions written in the Common Expression Language) are enforced in code, so they hold when a prompt is forgotten.

Checks its own "done"

Side-effecting tool calls go into a durable ledger. After each turn, what Nous says it did is checked against what ran. Background work is scored by a separate, deterministic scorer (fixed rules, no model), not by the agent.

Thinks in frames, not one chat loop

Each turn runs under one frame, which sets the memories, tools and models that matter, and with recording on the reason it was chosen is kept. A critic watches. The parts come from Marvin Minsky's book The Society of Mind: frames, K-lines (learned procedures that bring back what a kind of work needs), censors.

Acts on its own and builds its own UI

Heartbeat checks (checks it runs on a timer), schedules and multi-step plans run without a message from you. When a plan step needs you (plan approvals are opt-in), Nous puts an approval card with its recommendation in the companion app.

The companion: a screen the agent composes

When something is better as an interface than as text, Nous builds it. An escalation comes with options, the recommendation selected and the reasoning beside it, and your tap is recorded against the decision it answers.

The companion installs as a web app from your Nous server, and a native Android beta adds push notifications. It writes into the same conversation as Telegram. Nous puts escalations, findings cards, reviews of actions it took, small apps with live charts and tables, and (opt-in) plan approval gates there.

More about the companion
The Nous companion on a phone: an escalation card asking 'Deploy 1.8.2-rc.1 to staging?', with a summary of why, the risk that staging restarts for about a minute, three evidence tiles (3 time zones tested, 42 of 42 tests passed, Node 20.11 pinned in CI), and three options: Deploy now (recommended), Don't deploy yet, and Ask me later.
Sample data An escalation Nous composed in the companion: the options, the recommendation first, the evidence beside it.

Nous and an agent with memory

Many agents now keep facts or chat summaries and recall them by similarity. That is the floor Nous starts from. The table compares the two kinds of agent, not any one product.

AreaAn agent with memoryNous
What it keepsFacts and summaries of past chatsTyped memories, and every decision with its reasons and confidence
Why it actedGone when the turn endsWith recording on: the frame and its reason for each turn, a reason for each tool call
OutcomesNot trackedDecisions reviewed against what happened; Brier scores track how well its confidence matched results (calibration)
Getting betterMore stored factsProcedures from what worked, through a lesson gate; weak ones revised or retired
RulesInstructions in the promptCensors and guardrails that block the action in code
Saying "done"Taken on trustChecked against a ledger of the calls that ran; background work scored separately
InitiativeAnswers when askedHeartbeat checks, schedules and plans that wait for your approval

Memory is the substrate. Sleep keeps it honest.

Every turn runs the same loop: sense, frame, recall, deliberate, act, monitor, learn. Episodes, facts, procedures and censors live in one PostgreSQL database with pgvector, its extension for search by meaning.

After two idle hours Nous runs a sleep cycle: it consolidates memories (compressing old episodes and merging similar facts), links them, resolves contradictions and prunes dead links. The dashboard keeps a journal of each sleep.

How memory works
The Consolidation view in the Nous dashboard: the last 17 sleeps as a chart of new facts above the line and facts retired as stale below it, then one line per sleep (for example 3 new facts, 1 merge, 2 retired as stale, 1 contradiction resolved, 1 new procedure; graph links added and pruned), and the start of one sleep's report with what it learned.
Sample data The Consolidation view: the last sleeps, one sentence for each, and the report of one sleep.

The agent runs on your machine

Clone the repository, put your Anthropic API key in .env and start the containers. Migrations run on startup.

Read the quickstart
  • Python 3.12+
  • PostgreSQL 17
  • Docker Compose
  • Anthropic API

4

database schemas in one PostgreSQL

5

tools on its Model Context Protocol (MCP) server

6

cognitive frames in the seed data

Questions about Nous

Short answers, taken from the repository's own docs.

Read the full quickstart

Most agents have memory now. What is different?

Nous keeps why it acted as well as what it learned: decisions with reasons and confidence, graded against outcomes. It learns procedures from what worked, blocks known failures in code and checks its own claims against a ledger.

Can I see why Nous did something?

Yes. The dashboard shows each turn's frame and its reason, the reason for each tool call and every decision record. Turn and tool-call recording is opt-in.

What is the companion app?

A screen Nous composes: approval cards, action reviews and small live apps. It installs as a web app from your server, with an Android beta that adds push notifications.

Is Nous open source?

Yes, under the Apache 2.0 licence, on GitHub.

What does Nous run on?

Python 3.12+ and PostgreSQL 17 with pgvector, in Docker Compose. It thinks with Claude through the Anthropic API; an optional OpenAI key turns on embeddings, numbers that stand for a text's meaning, for search by meaning.

How do I talk to Nous?

Over the REST API, through its MCP server, with the optional Telegram bot, or in the companion app.