Long-term memory for an AI agent

Nous keeps episodes, facts, procedures, censors and working memory in PostgreSQL with pgvector, and finds them again by full-text, vector and graph search.

Get Nous on GitHub See the architecture

Runs on PostgreSQL 17 with pgvector.

Memory · FactsEpisodes · Procedures · Censors

CI runs on Node 22From the episode "Build failed on Node 20"current

CI runs on Node 20Contradicted by a newer factsuperseded

The docs job lints MarkdownActionablecurrent

Pip wheels are cached between runsFrom a resolved decisioncurrent

Deploys need an approvalCorrected by you, kept as a principlecorrection

The weekly digest goes out on MondayDate-anchoredcurrent

Release notes live in CHANGELOG.mdFrom an ingested documentcurrent

Supersessionnewer wins

CI runs on Node 22replaces "CI runs on Node 20"

Recall serves the newer fact

Five kinds of Nous memory. Each with its own lifecycle.

Episodes: memory of what happened

Each conversation is summarised into an episode. Keeping the verbatim transcript in chunks beside it is opt-in.

Episode · debug frameYesterday

Build failed on Node 20A native module would not compile; the build passed after pinning Node 22.

Facts extractedCI runs on Node 22 · the old Node 20 fact superseded2

Decision linkedPin CI to Node 22 after the build failed on 200.72

LessonCheck the runtime version before chasing a test failure

Linked in the graphTo the facts, the decision and the procedure it fed

Transcript chunksOff by defaultopt-in

Facts: memory that gets superseded

Facts are scored before they are stored, and a newer fact that contradicts an older one replaces it.

CI runs on Node 22current

CI runs on Node 20superseded

AdmissionScored before it is stored

TagActionable or not

SourceEpisode, document or correction

ExtractionText fenced off as data, not instructions

GraphLinked to decisions and episodes

Procedures: memory of skills

Learned K-lines, and skills taught with learn_skill from a URL, a file or inline markdown.

Upgrade Node in CILearned from 2 decisionsK-line

Write release notesTaught from a markdown fileskill

DeliveredIn full, when recalled

Review dependenciesTaught from a URLskill

Recover a failed deployLearned from an error recoveryK-line

Track recordHow well each one works

Weak or staleReviewed, revised or retired

Censors: memory that blocks actions

A censor is a "don't do this" rule, made when Nous finds a failure mode. It blocks a matching action.

Censorblocked

No force-push to main

git push --force

Made afterA failure Nous found

Ask before deleting a bucketactive

No secrets in commit messagesactive

Read-only check firstUnblocks when the check passes

RecalledWith the other memory types

Working memory holds the task

The state of the current task, cleaned up on a timer once the work is done.

Working memorythis task

GoalGet the build green

OpenRerun on the branch

DonePinned Node 22 in .nvmrc

Framedebug

Recalled for this task1 episode, 2 facts, 1 procedure

CleanupTimed, after the task

Hybrid recall across Nous memory

Full-text and vector results are fused by Reciprocal Rank Fusion, with a relevance floor and a staleness penalty.

Recall then spreads through the knowledge graph from facts to decisions, episodes and procedures, and shows contradictions as it goes. The context engine fits what it found into a token budget for the turn's frame.

See the turn loop

recall_deep: CI node version

Fused: full-text + vectorRRF

CI runs on Node 22fact

Build failed on Node 20episode

Pin CI to Node 22decision

Through the graphspreading activation

Upgrade Node in CIprocedure

Cache pip wheels between runsdecision

Contradiction

CI runs on Node 20Superseded by "CI runs on Node 22"older

Facts that change

When a newer fact contradicts an older one, Nous marks the older fact superseded and ranks it below the newer one, so recall serves what holds now and the old fact is still there to read.

Sleep consolidates Nous memory

When Nous has been idle for two hours by default, it sleeps. The sleep cycle reorganises memory instead of answering anyone.

A reviewable changelog of what each cycle changed is opt-in, as the consolidation audit.

Sleep cycledone

Consolidates and links memories✓

Backfills orphans into the graph✓

Re-links episodes✓

Resolves contradictions✓

Recovers abandoned conversations✓

Cleans up dead edges✓

Clusters decisions for new procedures✓

How Nous learns a procedure in 3 steps

1. Finds a lesson

From clusters of successful decisions, episode lessons and error recoveries.

2 resolved decisionscluster

1 episode lessonepisode

1 error recoverymonitor

2. Passes the lesson gate

The gate wants cited evidence and refuses a lesson that an existing procedure already teaches.

Lesson gatepassed

Evidence citedyes

Already taughtno

3. Lives as a procedure

Procedures track how well they work. Weak or stale ones are reviewed, then revised or retired.

Upgrade Node in CIin use

Old Python pin stepsretired

Release checklistreview