Docs

Local-first memory for coding agents: plain files you own, a background dream that reviews them, and nothing changes until you approve it.

Quickstart

Everything lives as plain files on your machine; there is no account and no hosted service. Requires Node 22 or newer. Run init: it finds the agents on this machine and wires up the ones it finds.

npx nexorum init

What init changes

  • Claude Code: merges a SessionStart and a Stop hook into ~/.claude/settings.json (created if missing), backing the file up to settings.json.nexorum-bak before the first change. Existing hooks are never removed, and running init twice does not add them twice. It registers the MCP server with claude mcp add nexorum -- npx -y nexorum mcp, or prints that command if claude is not on your PATH.
  • Recall before every prompt (optional): npm install -g nexorum, then nexorum init --claude-code --prompt-recall adds a UserPromptSubmit hook. It needs the installed command because it runs before every prompt, where npx start-up time adds up.
  • Codex: runs codex mcp add nexorum -- npx -y nexorum mcp (or prints it with the TOML), and writes a short marked block into AGENTS.md in the current folder so Codex actually recalls on its own. Your text is kept and a backup is written; --dir picks another folder, --no-agents-md skips it.
  • Hermes, Cursor, Claude Desktop: adds the MCP server to their configuration, with a backup.

Nothing else. Preview with npx nexorum init --dry-run. Any other MCP client can run npx -y nexorum mcp.

Your first session

Start your agent as usual, inside a project folder. At session start the hook injects a small digest of that project's memory (empty at first). The agent can call tools such as remember and recall. When the session stops, the transcript is saved, with secrets scrubbed, as a pending transcript. You can add notes yourself too:

nexorum remember "Run tests with pnpm test:unit, not npm test"
nexorum recall "how do I run the tests"
nexorum status

Dream, review, apply

Once a few sessions have piled up, consolidate them into the wiki. With your own key:

export ANTHROPIC_API_KEY="..."
nexorum dream          # prints what it selected and a token estimate, then asks Proceed? [y/N]
nexorum proposals
nexorum diff
nexorum apply          # or: nexorum reject

Without a key, ask your agent to dream: it calls dream_prepare, writes the pages and calls dream_submit. Either way the result is a proposal. apply writes each changed page to the live wiki but skips any page you changed since the dream started, and lists it. Every write is a version you can restore.

Concepts

The four layers

LayerWhat it isWhere
TranscriptsA record of a session (user, assistant and tool events), secrets scrubbed. Raw material for dreaming.transcripts/<id>.json
NotesShort memories added by an agent (remember) or by you.notes.jsonl
WikiSmall linked markdown pages, organised by dreams and editable by you, with an index.wiki/
ContextThe top layer: the index, kept small and injected at session start (about 4,096 characters; the Claude Code hook caps it at 10,000).wiki/_index.md

Space = project

Memory is split into spaces. A space is chosen by --space NAME, otherwise $NEXORUM_SPACE, otherwise the current folder's name (characters outside A-Za-z0-9_.- become -, at most 64 characters). One project is one space, and projects do not see each other's memory.

On-disk layout

Everything is under $NEXORUM_HOME (default ~/.nexorum). Per space, under spaces/<space>/:

wiki/            your live markdown pages; /deploys.md is wiki/deploys.md
  _index.md      the index (the context digest)
transcripts/     one file per recorded session
notes.jsonl      one note per line
history/         a copy of every page each time it changed, plus a log
proposals/       each dream's staged wiki, waiting for your review

Folders inside wiki/ are allowed. Writes are atomic (temporary file, then rename). The wiki is ordinary markdown: edit it, or commit it to git. If you change a page after a dream started, apply skips it instead of overwriting you.

History and restore

nexorum history
nexorum history /deploys.md
nexorum restore /deploys.md --version 3
nexorum retention --days 90

CLI reference

One binary, nexorum. npx nexorum <command> works without installing anything. Global flags: --space NAME, --help, --version. Exit codes: 0 ok, 1 runtime error, 2 usage or configuration error.

CommandWhat it does
initWire hooks and the MCP server into the clients it finds. --claude-code --codex --hermes --cursor --claude-desktop --all --dry-run --home DIR --dir DIR --no-agents-md --prompt-recall
mcpRun the MCP server on stdio.
hooksession-start | user-prompt | stop: Claude Code hook entry points (JSON on stdin).
rememberSave a note.
recallSearch notes and wiki. --limit N --kind note|wiki --since DATE
contextPrint the digest loaded at session start. --max-chars N
statusCounts: notes, wiki pages, pending and dreamed transcripts, proposals.
logStore a transcript from JSON events. --file F | - --source S --id ID
import ompStore omp sessions as transcripts. --dir D --session FILE --all --since DATE
dreamConsolidate pending transcripts and notes into a proposal. --budget TOKENS --instructions "..." --yes --dry-run --apply --since DATE --max-inputs N (1 to 200, default 50)
dream --if-dueFor schedulers: dream only when at least N (3) transcripts are pending, the newest is M (10) minutes old and the last dream H (6) hours old. --min-pending N --idle-minutes M --cooldown-hours H
doctorRead-only health check, PASS / WARN / FAIL per line, exit 1 on FAIL. --json
proposalsList proposals and their status.
diff [id]Line diff of a proposal against the live wiki (default: the newest one in review).
apply [id]Write a proposal to the live wiki, skipping pages changed since the dream started. --force
reject [id]Discard a proposal.
restore <path>Bring back an earlier version of a page. --version N
history [path]Versions of one page, or every change.
retentionRemove old dreamed transcripts and history. --days N (default 30)

Common flags, exit codes, environment

--space NAME picks the space for any command that acts on one. Exit codes: 0 success, 2 a usage problem (unknown command, bad flag, or a dream with no API key or model, with a message saying what to set), 1 anything else. hook always exits 0, so it can never block a session.

VariableMeaning
NEXORUM_HOMEStorage root. Default ~/.nexorum.
NEXORUM_SPACESpace when --space is not given. Default: the current folder's name.
NEXORUM_LLM_PROVIDERanthropic (default) or openai (any OpenAI-compatible endpoint).
NEXORUM_LLM_API_KEYAPI key. Falls back to ANTHROPIC_API_KEY (anthropic) or OPENAI_API_KEY (openai).
NEXORUM_LLM_BASE_URLEndpoint base URL. For openai the default is http://localhost:20128/v1.
NEXORUM_ANALYZER_MODELModel for analyzers. Default claude-haiku-5-5 on anthropic; required on openai.
NEXORUM_ORGANIZER_MODELModel for the organizer. Same defaults.
NEXORUM_PROMPT_RECALL0 turns off the recall that the prompt hook adds.
NEXORUM_DEBUG1 prints full stack traces on errors.

MCP server

nexorum mcp speaks standard MCP over stdio and serves 17 tools plus the nexorum://context resource.

GroupTools
Notesremember update_note forget list_notes
Recallrecall search_documents
Contextcontext
Wikiread_document list_documents related_documents document_history
Sessionssave_transcript memory_status
Review (read only)list_proposals show_proposal
Dream with no keydream_prepare dream_submit
# Claude Code
claude mcp add nexorum -- npx -y nexorum mcp
# Codex
codex mcp add nexorum -- npx -y nexorum mcp
# any client
{ "mcpServers": { "nexorum": { "command": "npx", "args": ["-y", "nexorum", "mcp"] } } }

The agent can read proposals but never apply them: applying is a command you run.

Other clients

Clients that take an mcpServers JSON block (Cursor, Claude Desktop, Antigravity, Hermes Agent, omp, OpenClaw and others) accept the generic block above. Where the file lives differs per client; nexorum init writes it for Cursor, Claude Desktop and Hermes. Checked with the official MCP SDK client; Claude Code and Codex use their own documented commands. If a client does not pick it up, check its MCP docs for where the block goes, then run nexorum doctor.

Claude Code hooks

HookCommandWhat it does
SessionStartnexorum hook session-startInjects the context digest (empty memory injects nothing).
UserPromptSubmitnexorum hook user-promptOptional. Adds matching memory before a prompt, only when it matches.
Stopnexorum hook stopSaves the session transcript, scrubbed, for a later dream.

Hooks always exit 0, so a hook can never block a prompt. NEXORUM_PROMPT_RECALL=0 turns the prompt recall off.

Dreaming

How a run works

  1. Pick inputs: pending transcripts (and notes) since the last dream, at most --max-inputs.
  2. Estimate the tokens and ask before spending (skip the question with --yes).
  3. Copy the live wiki to a staging wiki. Nothing touches the live wiki during the run.
  4. One analyzer per input, three at a time (inputs over 120,000 characters are split into parts): it verifies what the pages claim against the input, enriches them with exact details (commands, flags, numbers, dates) and organizes them into small linked pages.
  5. One organizer: merges duplicates, fixes links and keeps _index.md current.
  6. The staged changes become a proposal for you to review.

The agents only have document tools (list_docs, read_doc, grep_docs, write_doc, edit_doc, delete_doc, rename_doc, submit). There is no shell, network or file access.

Providers

Anthropic by default (ANTHROPIC_API_KEY or NEXORUM_LLM_API_KEY), or any OpenAI-compatible chat-completions endpoint with tool calling, including a local router: NEXORUM_LLM_PROVIDER=openai and NEXORUM_LLM_BASE_URL. Choose models with NEXORUM_ANALYZER_MODEL and NEXORUM_ORGANIZER_MODEL (default claude-haiku-5-5 for Anthropic; required for an OpenAI-compatible endpoint). Transient errors (429, 5xx, 529) are retried with backoff; the key never appears in output.

Token budgets

--budget TOKENS caps a run (default 3,000,000; a dream whose estimate is above it is refused). The cap is checked before each model call, so a run can overshoot only by the calls already in flight. You see progress at 50, 80 and 100 percent.

Without a key

Ask the agent you already run to dream. dream_prepare returns the rules, the current wiki and the new inputs; the agent writes the pages and calls dream_submit. The result is the same kind of proposal.

BM25 keyword search over notes and wiki pages, with light stemming and extra weight on page titles. No embeddings and no vector database: results are deterministic and fast, and the agent can follow [[links]] from the index.

Security model

  • Transcripts, notes and pages are treated as data, never as instructions; the dream prompts say so explicitly.
  • Secret patterns (API keys, tokens, private keys, JWTs, credentials in URLs and assignments) are replaced with [REDACTED:kind] before anything is written, including what a dream writes. This catches known patterns, not everything.
  • A dream only writes a proposal. Applying is always a command you run; a page changed since the dream started is skipped.
  • Every config file init edits is backed up first. Page paths are validated, so nothing is written outside the memory folder.
  • No telemetry. The only network traffic is a dream with your key, to the provider you set.

Examples

Dream every night with a scheduler

Dreams only when there is enough new material, nobody is mid-session and the last dream is old enough:

# cron (Linux, macOS)
0 3 * * *  cd ~/projects/orbit-api && nexorum dream --if-due --yes

# Windows Task Scheduler action
nexorum dream --if-due --yes --space orbit-api

Store a session from another agent

echo '{"source":"my-agent","events":[{"role":"user","content":"deploys run with make release"},{"role":"assistant","content":"noted"}]}' \
  | nexorum log --id session-42

Dream with a local or OpenAI-compatible model

export NEXORUM_LLM_PROVIDER=openai
export NEXORUM_LLM_BASE_URL=http://localhost:20128/v1
export NEXORUM_ANALYZER_MODEL=your-model NEXORUM_ORGANIZER_MODEL=your-model
nexorum dream --budget 500000

Review before anything changes

nexorum dream --dry-run     # show what would be selected and the estimate
nexorum dream --yes
nexorum diff                # line diff against the live wiki
nexorum apply               # or: nexorum reject
nexorum history /deploys.md
nexorum restore /deploys.md --version 2

Troubleshooting

Start with doctor

nexorum doctor checks Node, the memory folder, the hooks, the MCP registration and the LLM settings, one PASS / WARN / FAIL line each, with a hint for every warning. It never changes anything.

"No API key for provider"

Set NEXORUM_LLM_API_KEY (or ANTHROPIC_API_KEY) for nexorum dream, or dream through your agent with dream_prepare / dream_submit, which needs no key.

The dream was refused: estimate above the budget

Raise --budget, or dream on fewer inputs with --max-inputs N or --since DATE.

apply skipped a page

The page changed after the dream started, so it was not overwritten. Run a new dream, or use nexorum apply --force to overwrite the changed live files.

The agent does not seem to use its memory

Check that the SessionStart hook is installed (nexorum doctor), and for Codex that the AGENTS.md block exists (nexorum init --codex). Memory is per project folder: make sure you are in the same folder, or pass --space.

Git Bash on Windows turns /page.md into a Windows path

Git Bash rewrites arguments that start with /. Prefix the command with MSYS_NO_PATHCONV=1, or run it from PowerShell or cmd.

The prompt-recall hook is slow

It needs the installed command: npm install -g nexorum. Through npx every prompt pays the start-up time. Turn it off with NEXORUM_PROMPT_RECALL=0.

Simulation

/try runs Nexorum's own engine in your browser: the same BM25 search, digest, secret scrubber, line diff and dream engine as the CLI, copied unchanged from the package. Recorded replays a scripted example (an agent forgets a fact between sessions, a dream rewrites its notes into a small wiki, and the same question gets a better answer); no model runs, but every search, redaction, staging write and diff is real. Live, when the site has it switched on, runs the same flow with a real model through a capped proxy (/api/sim/status, /api/sim/v1/messages): one analyzer per input and one organizer, a token budget per visit, requests rate-limited per visitor and a daily budget for the site. The tools run in your browser and nothing is saved.

Privacy

Local: notes, transcripts, wiki and history are files under ~/.nexorum. Dreaming sends transcripts, notes and wiki pages to the LLM you configure, and nowhere else. Delete the folder to delete the memory. More on the privacy page.

FAQ

Do I need an API key?

No. You can dream through the agent you already use. A key only lets nexorum dream run on its own.

Which agents work?

Claude Code, Codex, Hermes, Cursor, Claude Desktop, and any MCP client over stdio. Not yet tested in every MCP client.

Can I edit the wiki by hand?

Yes. It is plain markdown. A dream that started before your edit will not overwrite it.

How do I uninstall?

Remove the hooks from ~/.claude/settings.json (or restore the .nexorum-bak backup), remove the MCP server from your client, and delete ~/.nexorum.

What is $NEXR?

The community token for Nexorum (contract: Posted here at launch). You never need it to use the software.