User guide

Last verified against the code: 2026-11-14 (0.10.1)

This guide assumes you have never used Neverest. Read the first six sections in order; the rest is reference to come back to.

What Neverest is

Neverest is the relay between models. You can build, fix, and deploy one project with more than one model. Neverest keeps one log of that project on your own computer. When the model changes, the next one is given what was done, what you corrected, and what was deployed, so it continues the same project instead of starting over.

The handoff is a record, not an order. Overnight, Neverest still turns repeated surprises into short lessons for the agents on this machine. A lesson describes what was seen. It is never an instruction.

Nothing in the project log leaves your computer. Sharing, if you turn it on, moves lessons, never the relay log and never your conversations.

One project, more than one model

After neverest is installed:

neverest proxy

Point each app at http://127.0.0.1:11435/v1 (OpenAI-shaped) or http://127.0.0.1:11435 (Anthropic-shaped). Send the header x-neverest-project with the project path, the same value from every model. NEVEREST_ROUTES is a JSON map of model-name prefix to server, so one proxy fronts several models. Longer prefixes win.

neverest relay prints the handoff for the project in the current directory. Copy it into a model that is not on the proxy. Record something the proxy did not see:

neverest relay --note "Use the blue button, not the red one." --kind correction
neverest relay --note "The sign-in screen is live at harbor.example." --kind deploy

The log is ~/.neverest/relay/, one file per project. The MCP tool relay reads and writes the same log. A different model receives the recent work plus every correction and deploy. The same model, whose request already contains the last reply, receives only the corrections and the deploys.

Before you start

You need:

• A terminal. Every step below is a command you type into one.
• macOS or Linux.
• uv, a tool that installs Python programs (it brings its own Python). If uv --version prints nothing, install it from docs.astral.sh/uv.
• An AI agent that Neverest can connect to. Claude Code gets the most out of it. Cursor, Codex, Gemini CLI, Claude Desktop and Windsurf work too.
• Access to the code. It is private until launch: write to contact@acificlabs.com.

Install it

git clone https://github.com/acific/neverest       # download the code
cd neverest && uv tool install .               # install it; `neverest` is now a command you can run
neverest status                                 # shows what it holds (nothing yet) and what to run next

At launch the first two lines become one, uv tool install neverest (or pipx install neverest); the package is not on PyPI yet.

Connect it to your agents

One command finds every AI agent on your computer and connects Neverest to each:

neverest setup --dry-run     # shows what it would change, and changes nothing
neverest setup               # does it

It does three things, and backs up any settings file before changing it:

• Tells your agent to hand each finished session to Neverest, and to accept reminders from it.
• Lets the agent ask Neverest questions while it works.
• Schedules the nightly sleep at 4 am, when lessons are made.

It is safe to run again; what is already connected is left alone. Restart any agent that was open so it picks up the change.

Your first day

1. Name the project. In the project directory, neverest proxy, and point the model you are using at it with the header x-neverest-project. Or skip the proxy and paste neverest relay into the next model.
2. Do the work. Ask the model to build or change something. If it is on the proxy, the exchange is on the log. If it is not, record what it did: neverest relay --note "…" --kind note.
3. Correct it in your own words. neverest relay --note "Use the blue button, not the red one." --kind correction. On the proxy, a message the same rules already call a correction is marked for you.
4. Record a deploy when one happened. neverest relay --note "The sign-in screen is live at harbor.example." --kind deploy.
5. Change the model. neverest relay prints what the next one should see. A different model gets the recent work, the corrections, and the deploys.

The nightly memory still runs. neverest setup connects the agents it finds and schedules sleep at 4 am. neverest status shows what the memory holds. neverest morning is last night's report. A single failed command is not a lesson; it has to happen again first. A correction from you is a lesson straight away, separate from the line on the relay log.

The words

• A session is one sitting with the agent: what you asked, what it did, how it ended.
• An error is a command that failed because of the agent's own mistake. Neverest keeps the command that caused it.
• A correction is a message where you told the agent it was wrong ("no, use uv", "the site isnt working", "you fix it", "dont ask"), anywhere in the message, including one you sent while it was working, or an action you refused. It is kept with the reply of the agent's that you were answering.
• Something the agent noticed: the agent saying, in its own words, that it was wrong or that something turned out differently.
• An environment failure is a command that failed because of the computer, not the agent (a tool not installed, a password or permission needed, the network, an interruption, a check whose answer was "no"). It is kept and can be found again, but never becomes a lesson.
• A note is something the agent chose to remember.

Errors, corrections and things the agent noticed are surprises. An error or a noticed surprise that repeats becomes a lesson; a correction is one the first time, because you said so.

A lesson always describes what happened. It is never an order. A lesson from one of your corrections quotes you: The user corrected the agent with "no, don't do that, this project uses uv" after the agent said "pip refused; I'll use pip with --break-system-packages". The agent reads it at the start of the next session and decides what to do with it.

The morning report

neverest morning (or ~/.neverest/morning.md):

# Neverest: last night (2026-10-22 04:00)

41 memories (12 surprises), 4 lessons, 3 open predictions, 2 confirmed, 0 failed. Archived 3 faded memories.

## New lessons
- The user corrected the agent for installing with pip; this project uses uv.

## Predictions confirmed
- A coming session will again meet: Bash (run the tests) failed: ModuleNotFoundError: No module named 'yaml'

It is five lines when nothing much happened. Read it with coffee.

Delegation

Sleep also counts how you delegate: how many times the agent offered to act instead of acting and how you answered (declined, approved, corrected, pushed past), how often it waited on a step only you could do, and how many times you stopped something it did, by kind of action (install, release, git, build…). It is one line in morning.md, for you. Since 0.8.0 the agent does not see it: shown to agents, this tally made four model families hand work back more (paper §7.4). What it means for the agent arrives at the moment instead, as the end-of-turn reminder.

Vetoing a lesson

Every lesson is a file in the project's memory folder (neverest paths shows it; the files are named neverest-<id>.md). Delete the file and the lesson is gone for good: sleep records the veto and never writes it again. The memories it came from are kept, so neverest recall can still find them.

The agent's tools

MCP is a standard way for AI agents to use outside tools. Once neverest setup has connected an agent, it has three tools from Neverest, and Neverest tells it when to use each:

• lessons(cwd): what memory holds, as short observations; called once at the start of a task.
• recall(query, k): memories matching the query; before something risky, or when an error looks familiar.
• remember(kind, …): a surprise as it happens: a correction (your words, verbatim, in said), an error, a surprise (expected, happened), or a note.

A local model

Neverest works with no AI model of its own. If you run one on your computer, its summaries and lessons read better. Without one, they are built by fixed rules and are a little dry ("Seen 3×: Bash (run the tests) failed: …").

The short way: install Ollama (a free app that runs models on your own computer), open it, and run:

neverest model setup

It looks at how much memory your computer has, picks a model that fits (a small one on a laptop, a larger one on a workstation), downloads it, and remembers the choice. Nothing leaves your machine. neverest model on its own shows what is in place and what would be downloaded. If a model already works, setup keeps it; name another with neverest model setup --model NAME.

It fetches two models. The writing model turns the dry summaries into better English at the next ingest and sleep. The meaning model (an embedding model) lets Neverest match by meaning, not just by shared words; the next sleep embeds everything again. Then "should I ask before releasing?" finds your "do it always dont ask", and corrections that say the same thing in other words become one theme, a lesson that quotes each of them. neverest status names both models.

Already running LM Studio or another OpenAI-compatible server? Neverest finds a model loaded there on its own. Set NEVEREST_LLM_URL and NEVEREST_LLM_MODEL if the server is elsewhere (OPERATIONS.md).

Any agent, any model

Everything lands in one store, so a correction made to a local model in a chat app is a lesson for Claude Code the next morning, and the other way round.

Sharing between memories

Two machines, or a team, can share what their memories learn through any folder they can all reach (Syncthing, Dropbox, a git repository, a network drive):

neverest share sync ~/Sync/neverest        # once by hand, or:
export NEVEREST_SHARE_DIR=~/Sync/neverest  # and every sleep syncs

Only lessons leave, never your sessions. By default only lessons from errors and the agent's own surprises: lessons from your corrections quote your words, so they are shared only with --corrections (for your own machines). A lesson from another memory arrives as a candidate: it is tested by your own sessions, grows stronger if it comes true here (and tells its origin), and fades if it does not. neverest share list shows where each lesson came from; neverest share revoke HASH withdraws one of yours from other memories at their next sync; the next render removes its managed file (neverest sleep syncs and then renders). Deleting its file vetoes it here, as always.

To put Neverest on another machine (macOS or Linux), run neverest share invite here, in your own terminal, and paste the line it prints there: it installs everything, wires every agent and joins the commons. The line contains the commons token; keep it private.

Or through the commons by hand, which needs no shared folder (a token until launch: copy ~/.neverest/commons-token from a machine that has it):

neverest share sync https://neverest.acific.com/commons/    # every sleep syncs there afterwards

Every record is signed with this memory's key (~/.neverest/key; back it up, it is the memory's identity), so no one can publish or revoke in its name. neverest share whoami prints its id; neverest share trust ID, run for each teammate's id, makes a team: only listed memories are heard.

Commands

What setup does, by hand

You do not need this section if neverest setup worked. It is here if you would rather make the changes yourself, or want to know exactly what was changed. neverest hook prints the same lines.

1. Read every session when it ends. Add to ~/.claude/settings.json:

   { "hooks": { "SessionEnd": [ { "hooks": [ { "type": "command", "command": "neverest ingest --quiet" } ] } ] } }
   

2. Let the agent ask questions mid-task: claude mcp add neverest -- neverest serve
3. Sleep every night: (crontab -l; echo "0 4 * * * neverest sleep") | crontab -
4. Remind the agent when it matters: add a UserPromptSubmit hook beside the SessionEnd one:

   "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "neverest prime", "timeout": 10 } ] } ]
   

   When what you type has to do with a lesson, the lesson is put beside your message for the agent; otherwise nothing happens. Try it by hand first: neverest prime "want me to push this?".
5. Catch the agent at the moment: the same command on two more hooks.

   "Stop": [ { "hooks": [ { "type": "command", "command": "neverest prime", "timeout": 10 } ] } ],
   "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "neverest prime", "timeout": 10 } ] } ]
   

   When the agent ends a reply by handing a decision back to you, and you have corrected exactly that before, it is shown your earlier corrections and carries on (once; it is never stopped twice in a row). Before a command like one that failed before, the agent is shown the failure. Half of all sessions get no reminders, on purpose, so neverest measure can tell whether the reminders work; NEVEREST_HOLDOUT=0 turns that off.

FAQ

Does anything leave my computer? Not unless you turn sharing on. Everything is in ~/.neverest and your agent's own folders, and the local model is local. If you do share (see "Sharing between memories" above), only lessons leave, never your sessions.

Does it change the memories Claude Code writes itself? No. It owns only the neverest-*.md files and one marked section of MEMORY.md.

Can it tell the agent to do something? No, by design. Lessons state what happened. See the paper §3.5 for why.

Why did a single error not become a lesson? An error has to repeat; a one-off failure is noise. A single correction is a lesson at once, because you said so.

A lesson is wrong. What do I do? Delete its file (see "Vetoing a lesson" above). It is never written again.

How do I start over? Delete ~/.neverest and the neverest-*.md files; run neverest ingest again.

Troubleshooting

For a request without memory, send x-neverest: off to the proxy. It forwards the request to the same model server with no memory injection or recording, including Anthropic requests. Bad shared records and bad MCP requests no longer stop later valid input (0.10.1).