Archivum documentation

Quickstart

Archivum is local-first memory for coding agents. Everything lives as plain files on your machine; there is no account and no hosted service. Requires Node 22 or newer.

1. Run init. It detects Claude Code (~/.claude) and Codex (~/.codex or codex on your PATH) and wires up whatever it finds.

npx archivum init

What init changes

• Claude Code: merges a SessionStart and a Stop hook into ~/.claude/settings.json (created if missing). Before the first change it backs the file up to settings.json.archivum-bak. Existing hooks are never removed and running init twice does not add the hooks twice. It also registers the MCP server with claude mcp add archivum -- npx -y archivum-cli mcp, or prints that exact command if the claude binary is not found.
• Codex CLI: runs codex mcp add archivum -- npx -y archivum-cli mcp, or prints the command and the [mcp_servers.archivum] TOML if codex is not found.
• Nothing else. Preview with npx archivum-cli init --dry-run; limit it with --claude-code or --codex.

Your first session

Start your agent as usual, inside a project directory. At session start the hook injects a small digest of that project's memory (empty at first, so nothing is injected). The agent can call the MCP tools such as remember and recall. When the session stops, the hook saves the transcript, with secrets scrubbed, to your Archivum home as a pending transcript. You can also add notes yourself:

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

Dream

Once a few sessions have piled up, consolidate them into the wiki. Dreaming uses your LLM key (see Dreaming).

export ANTHROPIC_API_KEY="sk-ant-..."
archivum dream

It prints how many transcripts and notes it selected plus a rough token estimate, then asks Proceed? [y/N]. Nothing is written to your live wiki yet: the result is a proposal.

Review and apply

archivum proposals
archivum diff
archivum apply        # or: archivum reject

apply writes each changed file to the live wiki, but skips any file you changed since the dream started (and lists it). Every write is a version you can restore.

Concepts

The design is inspired by Anthropic's article The components of agent memory. Archivum is an independent project and is not affiliated with Anthropic; this page makes no claims about benefits beyond what is described here.

The four layers

Space = project

Memory is partitioned into spaces. A space is chosen by --space X, otherwise $ARCHIVUM_SPACE, otherwise the cwd's folder name (characters outside A-Za-z0-9_.- become -, at most 64 characters, fallback default). In practice one project is one space and projects do not see each other's memory.

What lives where

• Everything is under $ARCHIVUM_HOME (default ~/.archivum) on your disk.
• Your agent only sees memory through the digest the hook injects and the MCP tools.
• Only archivum dream sends anything to an LLM, using the provider you configured.

On-disk layout

Per space, under <home>/spaces/<space>/:

wiki/                 your live markdown pages; /quillon-tests.md is wiki/quillon-tests.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/<id>/      each dream's staged wiki, waiting for your review

Folders inside wiki/ are allowed. All writes are atomic (temp file then rename).

Edit by hand or commit to git

The live wiki is ordinary markdown. Open it in your editor, fix a page, delete one, or run git init inside wiki/ and commit it. Hand edits are safe: if you change a page after a dream started, apply sees the page has changed and skips it rather than overwriting you. Changes made outside the CLI are not recorded in the history log; only writes made by apply, restore and write are.

History and restore

Each history entry has an operation (create, update, delete, rename, restore) and an actor (user, dream:<id> or restore).

archivum history
archivum history /quillon-tests.md
archivum restore /quillon-tests.md --version 3

CLI reference

One binary, archivum. Output is human-readable text. Install nothing: npx archivum-cli <command> works, or install the package globally.

init

With no client flag, init configures every client it detects.

mcp, hook, log

• archivum mcp [--space X]: stdio MCP server (see MCP server).
• archivum hook session-start|stop: Claude Code hook entry points, reading hook JSON on stdin (see hooks).
• archivum log [--file F | -] [--source S] [--id ID]: append a transcript from a JSON file or stdin, either {"events":[...]} or a bare array of events, for agents without hooks. Each event is {"role":"user|assistant|system|tool","content":"...","name"?,"ts"?}.
• archivum import omp [--dir D] [--session FILE] [--all] [--since DATE] [--space S]: store omp sessions as transcripts. omp keeps sessions as JSONL under ~/.omp/agent/sessions (override with --dir or OMP_SESSIONS_DIR). By default it imports the sessions whose working directory is the current one; --all takes every session (each into the space named after its working directory) and --session takes one file. It is idempotent: the omp session id is the transcript id, so importing again after a session grew updates the same transcript and puts it back to pending. Thinking blocks are dropped, tool output is clipped to 4,000 characters, and known secret patterns are redacted.

remember, recall, context, status

archivum remember "text"
archivum recall "query" --limit 5
archivum context --max-chars 4096
archivum status

status prints the counts of notes, wiki pages and transcripts (pending and dreamed), proposals, the home path and the space.

dream

Selects the oldest pending transcripts (at most 50, or the --max-inputs value, and 6,000,000 characters) and unconsolidated notes (at most 300).

--if-due is for schedulers. It exits 0 after printing one line, not due: <reason>, unless at least --min-pending transcripts are pending, the newest transcript was last updated at least --idle-minutes ago and the last dream (the newest proposal) is at least --cooldown-hours old. When due it behaves like a normal dream: --yes is still required without a terminal and the result is still a proposal to review.

proposals, diff, apply, reject

restore, history, retention

doctor

archivum doctor [--space X] [--json] is a read-only health check. It prints one line per check, PASS, WARN or FAIL, with a hint where there is something to do, and exits 0 unless a check fails (then 1). With --json it prints an array of {name, status, detail, hint}. It makes no network call and never prints your API key (only set or missing).

Troubleshooting

• Start with archivum doctor. It tells you which file is unreadable, which hook is missing and what the LLM configuration lacks.
• A FAIL on space files means a file in the space is damaged. Archivum skips unreadable records instead of crashing, but cannot repair them: restore the named file from a backup or delete it.
• A WARN on claude hooks or mcp: run archivum init again (it is idempotent).
• A dream that says the estimate is above the budget: use --since DATE or --max-inputs N to dream fewer inputs, or raise --budget.
• To dream on a schedule (cron, Task Scheduler) run archivum dream --if-due --yes. See dream.

Common flags, exit codes, environment

--space X selects the space for the commands that act on one. A missing API key or model for dream exits with code 2 and a message saying what to set; hook always exits 0. Other failures exit non-zero with a message on stderr.

Examples

# preview what init would do
npx archivum init --dry-run

# a one-off dream with a smaller budget and a hint
archivum dream --budget 500000 --instructions "Focus on build and test commands" --yes

# log a transcript from an agent without hooks
cat session.json | archivum log - --source my-agent --id session-42

# review, then apply
archivum diff
archivum apply

MCP server

archivum mcp is a stdio MCP server (newline-delimited JSON-RPC 2.0, protocol 2025-06-18). It logs to stderr only. The space comes from ARCHIVUM_SPACE or the working directory, or --space.

All tools are read-only except remember and forget. By design there is no tool to start a dream or to apply a proposal: those spend your tokens or change your wiki, so you do them with the CLI.

It also exposes one resource, archivum://context, with the current context digest.

Claude Code

claude mcp add archivum -- npx -y archivum mcp

Codex CLI

Either use the command, or add the equivalent to ~/.codex/config.toml (see the Codex MCP docs):

codex mcp add archivum -- npx -y archivum mcp

[mcp_servers.archivum]
command = "npx"
args = ["-y", "archivum-cli", "mcp"]

Other clients

Clients that take an mcpServers JSON block, such as Antigravity, Hermes Agent, omp and OpenClaw, generally accept this shape:

{
  "mcpServers": {
    "archivum": {
      "command": "npx",
      "args": ["-y", "archivum-cli", "mcp"]
    }
  }
}

Where that goes differs per client; see Antigravity, Hermes Agent, omp and Codex.

Claude Code hooks

archivum init merges these into ~/.claude/settings.json; you can also add them yourself:

{
  "hooks": {
    "SessionStart": [
      { "hooks": [ { "type": "command", "command": "npx -y archivum-cli hook session-start" } ] }
    ],
    "Stop": [
      { "hooks": [ { "type": "command", "command": "npx -y archivum-cli hook stop" } ] }
    ]
  }
}

• SessionStart reads the hook JSON from stdin and prints the memory digest as additionalContext so Claude sees it. The output is capped at 10,000 characters. If the space has no context yet it prints nothing.
• Stop reads the session JSONL at transcript_path, converts it to events, scrubs secrets and saves transcripts/<session_id>.json. If the same session is saved again with new content it becomes pending again. It prints nothing.
• The space is ARCHIVUM_SPACE if set, otherwise the basename of the hook's cwd.
• Hooks never fail your session: they always exit 0, and errors go to stderr only when ARCHIVUM_DEBUG=1.

For agents without hooks, log transcripts yourself with archivum log and read context with archivum context or the MCP tools. omp has no hooks of this kind: run archivum import omp (for example before archivum dream) to turn its session files into transcripts.

Dreaming

A dream is a background pass that checks the wiki against recent transcripts and notes, fixes stale or wrong facts (marking dates and staleness), merges duplicates, links pages and keeps _index.md current. Nothing changes in your live wiki until you apply the result.

How a run works

1. Select. Pending transcripts (oldest first, at most 50 / 6,000,000 characters) and notes not yet consolidated (at most 300). Counts and a rough token estimate are printed and you confirm (or pass --yes). The run refuses if the estimate exceeds the budget.
2. Stage. The live wiki is copied into proposals/<id>/wiki, and the checksums of your live pages are remembered.
3. Analyze. One analyzer agent per input reads it against the staged wiki and writes what it learned. Large inputs are split.
4. Organize. One organizer agent merges duplicates, resolves conflicts, links pages and updates the index.
5. Propose. The result is saved as a proposal in review state. If the organizer fails after analyzers wrote, the proposal is still kept and marked partial.
6. Apply or reject. See below.

Providers

You bring the key. anthropic (default) uses the Messages API. openai works with any OpenAI-compatible /chat/completions endpoint that supports tool calling: a hosted provider, a local server, or a router such as 9router.

# Anthropic (default)
export ANTHROPIC_API_KEY="sk-ant-..."

# any OpenAI-compatible endpoint, e.g. a local router
export ARCHIVUM_LLM_PROVIDER=openai
export ARCHIVUM_LLM_BASE_URL="http://localhost:20128/v1"
export ARCHIVUM_LLM_API_KEY="..."
export ARCHIVUM_ANALYZER_MODEL="your-model"
export ARCHIVUM_ORGANIZER_MODEL="your-model"

Token budgets

Budgets are counted in tokens, not money; check your provider for pricing. The default budget is 3,000,000 tokens. Before running, dream prints a rough estimate from the size of the transcripts and existing wiki. It is an estimate only: actual usage depends on the model and how many turns the agents take. If a run hits the budget it stops with a budget-exhausted status and keeps what was staged for review.

Review first, apply skip rule, restore

• Dreaming never touches the live wiki. Use archivum diff, then apply or reject. (--apply on dream is opt-in.)
• apply writes a file only if the live page is still exactly what the dream started from; otherwise it is skipped and listed. --force overrides that.
• Applying records history, marks the proposal's transcripts dreamed and advances the notes marker.
• Every applied write is a version: archivum restore <path> --version N.

Security model

• Transcripts are untrusted data. They are given to the model in a labelled format and the agents are instructed to treat them as data, not instructions. Instructions hidden in a transcript could still influence a model; this reduces that risk, it does not remove it.
• Document-only tools. Dream agents can only list, read, grep, write, edit, delete and rename wiki documents, and submit. They have no shell and no network access.
• Secret scrubbing. API keys, bearer tokens, PEM blocks, AWS, GitHub, Slack and Google keys and JWTs are replaced by [REDACTED:<kind>] before transcripts are saved and on every wiki write. Pattern-based scrubbing cannot catch every secret.
• Review before apply and versioned restore are the final safety net.

Search

recall, search_documents and archivum recall use BM25 ranking over notes and wiki pages, with unicode-aware tokenising, light stemming and a higher weight for page names and titles. Results are deterministic. There are no embeddings and no vector database.

Why: the wiki is small and written to be navigated. The model starts from _index.md, follows links and searches by keyword, much like a person with a folder of notes. That needs no extra model, no index service and nothing to send off your machine, and a result can be explained by the words it matched. The trade-off is that purely semantic queries with no shared words can miss; the dream's linking and naming are meant to cover that.

Simulation (/try/)

The /try/ page is an interactive demo of memory and dreaming in your browser: a chat with a pretend coding agent, an animated stage showing the analyzer and organizer at work, and a panel with the context, wiki, notes, transcripts and the proposal diff you approve or reject. It never reads or writes your local Archivum files.

• Recorded (default): a scripted scenario. Nothing is sent anywhere.
• Live: a real model, paid for by the site, so you need no key. It is rate-limited, and when a limit is hit the page tells you and returns to Recorded. Your messages go to the site and its model provider, so type nothing private. Your own CLI memory never goes through the site.

Privacy

Secrets are scrubbed before transcripts are stored, but the scrubber is pattern-based. See the privacy notice for the website.

FAQ