Nexus
Sign inStart building
Guides / Brain

Memory for agents: recall, remember, entity, synthesize, forget

The five memory actions every connected agent uses, and how to connect agents such as Codex or OpenClaw.

The brain gives agents a small, fixed set of memory actions: recall, remember, entity, synthesize and forget. Together they are called MEMORY_VERBS v1. An agent uses them to save what it learns and look it up again in a later session, even from a different agent.

This guide explains what each action does, connects an agent to them, and shows how to try each one from the command line. The v1 contract is frozen: field names and meanings never change, and new fields are only ever added.

Time
10 minutes
For
Anyone giving Claude Code, Codex, OpenClaw or another MCP agent a memory that lasts between sessions

Before you start

  • A working brain. If you do not have one, run nexusbrain init first. See Setting up the brain for your AI agents.
  • An agent that supports MCP servers.
  • synthesize also needs a chat model key, such as ANTHROPIC_API_KEY. The other four actions work without one.

01What the five actions do

A fact is one short claim, such as "prefers dark mode", with a note of where it came from. Facts can be attached to an entity: a person, company or project, named by a slug such as people/alice-example.

  1. Print the protocol to see every action and its inputs.

    nexusbrain protocol

    You should seeA heading with MEMORY_VERBS v1, then one line per action such as remember(fact, provenance, ttl?, entity?, kind?, visibility?). Inputs ending in ? are optional.

  2. Print the full schemas when you need exact field types.

    nexusbrain protocol --json

    You should seeA JSON document with protocol_version, an input and response schema for each action, and the error schema.

ActionWhat it doesRequired inputsCost
rememberSaves one fact.fact, provenanceNo model call
recallReturns saved facts. With query it also searches your pages.NoneNo model call
entityReturns a short card about one known person, company or project.nameNo model call, usually under 100ms
synthesizeAnswers a broad question by reasoning across many pages, with sources and gaps.questionCalls a model. Slow and costs money.
forgetExpires a fact by id. The fact is kept for the audit trail, not deleted.idNo model call
Tip

Agents should use entity for one known subject, recall for facts and snippets, and synthesize only when the answer needs evidence combined from many pages.

02Connect your agent

nexusbrain serve --surface verbs starts an MCP server that offers exactly these five actions and nothing else. Without --surface verbs, nexusbrain serve offers every brain operation, and the five actions are included in that list too.

  1. Add the brain to Claude Code.

    claude mcp add nexusbrain -- nexusbrain serve --surface verbs

    You should seeClaude Code saves an MCP server named nexusbrain. It starts the server itself when a session begins.

  2. For Codex, OpenClaw or any other MCP client on the same machine, register the same command.

    Add a server that runs the command nexusbrain with the arguments serve --surface verbs. The server talks over standard input and output, the usual way to run a local MCP server. The OpenClaw plugin bundle for the brain declares a plain nexusbrain serve server, which offers the five actions alongside every other operation.

  3. If the brain runs on another machine, generate the setup for your agent.

    The other machine runs nexusbrain serve --http, and you create a token there with nexusbrain auth create. --agent accepts claude-code, codex, perplexity or generic. For Codex, the printed block sets NEXUS_BRAIN_REMOTE_TOKEN and runs codex mcp add with --bearer-token-env-var.

    nexusbrain connect https://brain.example.com/mcp --token <token> --agent codex

    You should seeA block starting # Paste into Codex: with the commands to run. Add --install to run them for you.

  4. Check that a server follows the contract.

    With no target, this starts the brain's own server and tests it. Use --target http://host:3131/mcp --token <token> for a remote server.

    nexusbrain protocol conformance

    You should seeA line per check, a count of passed, failed and skipped, and CONFORMANT at the end.

Warning

On the local engine only one process can open the database. While an agent session is running nexusbrain serve, nexusbrain remember and other commands in a terminal cannot open the brain. Try the commands below with the agent closed, or ask the agent to call the tools instead.

03Save and read back a memory

These are the three commands nexusbrain init prints at the end. The command line uses the same code as the MCP tools, so what works here works for agents.

  1. Save a fact about yourself.

    --provenance is required: a short note of where the fact came from, up to 500 characters. Set --entity whenever the fact is about someone or something, because a recall by entity will not find facts saved without one.

    nexusbrain remember "I prefer dark mode in every editor" --provenance demo --entity people/me

    You should seeremembered as fact #N and entity: people/me. Saving the same fact again prints already knew this and keeps the original id.

  2. Read facts about that entity.

    nexusbrain recall --entity people/me

    You should seeA line with the fact id (such as id=1), [people/me], the fact text, and its kind and confidence. Facts are listed newest first.

  3. Start a new agent session and ask about your editor preferences.

    You should seeThe agent calls recall and mentions dark mode.

Option for `remember`What it does
--entity <name or slug>Who or what the fact is about.
--kind <kind>One of event, preference, commitment, belief or fact (the default).
--ttl <when>When the fact expires: 30d, 12h, 45m, or a date such as 2026-07-12T00:00:00Z. Forms like P30D are rejected.
--visibility <world|private>world (the default) lets every connected agent read it. private keeps it to local command line reads.
--jsonPrint the raw response, including status: inserted, duplicate or superseded.

04Look things up with recall, entity and synthesize

  1. Recall facts and matching pages in one call, within a token budget.

    --query adds a search over your pages. --budget-tokens asks the brain to pack facts first, then page results, until the budget is used.

    nexusbrain recall --query "editor setup" --budget-tokens 2000

    You should seeA Facts: list, a Pages: list, and a budget: line showing tokens used and how many items were dropped.

  2. See only what was saved recently.

    nexusbrain recall --since "8 hours ago"

    You should seeFacts saved in the last eight hours.

  3. Get a card for one entity.

    nexusbrain entity "Alice Example"

    You should seeThe entity title and slug, then when available a summary, open threads and links, and a backlinks: N | active facts: N line. If nothing matches you get No entity found., with a Did you mean: list when there are close matches, instead of an error.

  4. Ask a broad question.

    nexusbrain synthesize "what is our payments strategy?"

    You should seeAn answer, then sources:, any gaps:, and a cost: line with the model and token counts.

Note

The recall command also accepts --today, --session <id>, --grep <text>, --include-expired, --as-context and --json. synthesize accepts --since and --until to limit the time window.

05Forget a fact

  1. Find the fact id.

    nexusbrain recall --entity people/me

    You should seeOne line per fact, each with id=N, the entity in brackets, the fact text, and its kind.

  2. Expire it.

    nexusbrain forget 42 --reason "no longer true"

    You should seeForgot fact id=42.

Note

Fact ids are numbers returned by remember and recall, never page slugs. Over MCP, forgetting a fact that is already expired succeeds with expired: false.

06Who can read a memory, and what gets tracked

  1. Check how your agents use memory.

    nexusbrain protocol stats --days 7

    You should seeMEMORY_VERBS usage for the last 7 days, one line per action, and the path of the local log file. Before any calls it says no verb calls recorded yet.

  • Memories saved with the default world visibility can be read by every agent connected to this brain, including agents on other machines that reach it over HTTP.
  • Agents connected over MCP, even on this machine, only ever see world facts. Facts saved with visibility: "private" are only returned to local command line reads such as nexusbrain recall.
  • nexusbrain protocol stats shows calls per action, error counts, average latency, how often entity found a match, and how long it took from install to the first action call. It reads a local log file only, and that data never leaves the machine. Use --days N to change the window from the default 30 days.

07Troubleshooting

provenance is required and must be non-empty.

Every remember needs a note of where the fact came from. Add --provenance "user said in chat" or similar.

synthesize needs an LLM and none is configured.

Set a chat model key, for example ANTHROPIC_API_KEY, or run nexusbrain config set anthropic_api_key <key>, then try again. recall and entity keep working without one.

A recall by entity prints No matching facts., but the fact was saved

The fact was probably saved without --entity. Try nexusbrain recall --grep <word> to find it, then save it again with an entity.

If an agent saved it, check whether it used visibility: "private". Private facts never reach MCP clients.

The command says the local database is already open through nexusbrain serve

An agent session is holding the local database. Close the session, or keep it and ask the agent to call the memory tools instead.

Unknown --surface when starting the server

The only accepted values are verbs and full.

No fact with id=42

The id does not exist in this brain or source. Run nexusbrain recall to see the ids of current facts. If it says is already expired, the fact was forgotten earlier.

Conformance ends with NOT CONFORMANT

Read the lines marked as failed for the check and the reason. Add --json for a machine readable report you can share through feedback.