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 tosettings.json.nexorum-bakbefore the first change. Existing hooks are never removed, and running init twice does not add them twice. It registers the MCP server withclaude mcp add nexorum -- npx -y nexorum mcp, or prints that command ifclaudeis not on your PATH. - Recall before every prompt (optional):
npm install -g nexorum, thennexorum init --claude-code --prompt-recalladds a UserPromptSubmit hook. It needs the installed command because it runs before every prompt, wherenpxstart-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 intoAGENTS.mdin the current folder so Codex actually recalls on its own. Your text is kept and a backup is written;--dirpicks another folder,--no-agents-mdskips 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
| Layer | What it is | Where |
|---|---|---|
| Transcripts | A record of a session (user, assistant and tool events), secrets scrubbed. Raw material for dreaming. | transcripts/<id>.json |
| Notes | Short memories added by an agent (remember) or by you. | notes.jsonl |
| Wiki | Small linked markdown pages, organised by dreams and editable by you, with an index. | wiki/ |
| Context | The 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.
| Command | What it does |
|---|---|
init | Wire 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 |
mcp | Run the MCP server on stdio. |
hook | session-start | user-prompt | stop: Claude Code hook entry points (JSON on stdin). |
remember | Save a note. |
recall | Search notes and wiki. --limit N --kind note|wiki --since DATE |
context | Print the digest loaded at session start. --max-chars N |
status | Counts: notes, wiki pages, pending and dreamed transcripts, proposals. |
log | Store a transcript from JSON events. --file F | - --source S --id ID |
import omp | Store omp sessions as transcripts. --dir D --session FILE --all --since DATE |
dream | Consolidate 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-due | For 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 |
doctor | Read-only health check, PASS / WARN / FAIL per line, exit 1 on FAIL. --json |
proposals | List 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. |
retention | Remove 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.
| Variable | Meaning |
|---|---|
NEXORUM_HOME | Storage root. Default ~/.nexorum. |
NEXORUM_SPACE | Space when --space is not given. Default: the current folder's name. |
NEXORUM_LLM_PROVIDER | anthropic (default) or openai (any OpenAI-compatible endpoint). |
NEXORUM_LLM_API_KEY | API key. Falls back to ANTHROPIC_API_KEY (anthropic) or OPENAI_API_KEY (openai). |
NEXORUM_LLM_BASE_URL | Endpoint base URL. For openai the default is http://localhost:20128/v1. |
NEXORUM_ANALYZER_MODEL | Model for analyzers. Default claude-haiku-5-5 on anthropic; required on openai. |
NEXORUM_ORGANIZER_MODEL | Model for the organizer. Same defaults. |
NEXORUM_PROMPT_RECALL | 0 turns off the recall that the prompt hook adds. |
NEXORUM_DEBUG | 1 prints full stack traces on errors. |
MCP server
nexorum mcp speaks standard MCP over stdio and serves 17 tools plus the nexorum://context resource.
| Group | Tools |
|---|---|
| Notes | remember update_note forget list_notes |
| Recall | recall search_documents |
| Context | context |
| Wiki | read_document list_documents related_documents document_history |
| Sessions | save_transcript memory_status |
| Review (read only) | list_proposals show_proposal |
| Dream with no key | dream_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
| Hook | Command | What it does |
|---|---|---|
| SessionStart | nexorum hook session-start | Injects the context digest (empty memory injects nothing). |
| UserPromptSubmit | nexorum hook user-prompt | Optional. Adds matching memory before a prompt, only when it matches. |
| Stop | nexorum hook stop | Saves 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
- Pick inputs: pending transcripts (and notes) since the last dream, at most
--max-inputs. - Estimate the tokens and ask before spending (skip the question with
--yes). - Copy the live wiki to a staging wiki. Nothing touches the live wiki during the run.
- 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.
- One organizer: merges duplicates, fixes links and keeps
_index.mdcurrent. - 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.
Search
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.