Skip to main content
Glama
Archivum

Archivum

Official
by tryarchivum

Archivum

Your agent forgets everything when the session ends. Archivum is the notebook it keeps.

Local-first long-term memory for AI agents: plain markdown on your disk, no accounts, and a review-first "dream" that tidies the notes while you sleep.

npm CI License: MIT Node 22+ MCP server zero runtime deps

Bahasa Indonesia · Quick start · How it works · Does it help? · Use it from your agent · FAQ · Docs

npx archivum-cli init


NOTE

Beta. Everything below marked "verified" was run;Known limits lists what was not (hooks not run in a real Claude Code session, Anthropic provider not run against the real API, most MCP clients untested).

The idea in one minute

Agents are good within a session and amnesiac across them. Archivum gives them four layers of memory, inspired by Anthropic's The components of agent memory:

Layer

What it is

Who writes it

Transcripts

append-only session logs (secrets redacted before they hit disk)

Claude Code hooks, archivum log, archivum import omp

Notes

short facts: a command, a decision, a gotcha

your agent, through remember

Wiki

a few linked markdown files plus an _index.md; every write is a version

the dream, after you approve

Context

a short digest injected at session start

derived from the wiki index

A dream reads pending transcripts and notes with hindsight, checks the wiki against them, corrects or marks stale facts, merges duplicates and links related pages (one analyzer per input, then one organizer). It has document tools only (no shell, no network), works on a staging copy and hands you a proposal. Nothing touches your live wiki until you run archivum apply.

Related MCP server: obsidian_shared_memory

Quick start

npx archivum-cli init        # wires Claude Code (hooks + MCP) and Codex; add --dry-run to preview
archivum remember "tests: npm test -- --runInBand (parallel runs hit the shared sqlite file)"
archivum recall "how do I run tests"

Dreaming uses your model and your key (you pay your provider, we never see it):

export ARCHIVUM_LLM_API_KEY=...        # or ANTHROPIC_API_KEY / OPENAI_API_KEY
archivum dream                         # prints a token estimate, asks before spending
archivum diff && archivum apply        # review, then accept

Anything OpenAI-compatible works (ARCHIVUM_LLM_PROVIDER=openai, ARCHIVUM_LLM_BASE_URL=...), including local routers.

How it works

flowchart LR
  A[Agent session] -->|hooks, log, import| T[(Transcripts)]
  A -->|remember| N[(Notes)]
  T --> D{{dream: analyzers then organizer}}
  N --> D
  D -->|proposal, never live| P[Proposal diff]
  P -->|you: apply| W[(Wiki + _index.md)]
  W -->|digest at session start| A
  W -->|recall, read_document| A

Search is BM25 over notes and wiki pages plus the wiki's own links: no embeddings, no vector database, nothing to host.

Does it actually help?

We measured it, and it is mixed in an honest way. Synthetic scenarios, answers graded by regex, question answering by the same model with different contexts:

Scenario

No memory

Append-only notes + BM25

Dreamed wiki

4 small projects (5 to 9 sessions each)

0%

83 to 100%

100%

scale: 48 sessions, 31 distractors, facts that change 2 to 4 times (GPT-5.6 luna)

0%

38%

94%

scale (Gemini 3.8 flash)

0%

38%

100%

  • On small inputs the raw notes fit the search window, so the dream only ties the naive baseline. Its value there is structure and correctness marks.

  • On a larger, noisy history, naive retrieval pulls stale or look-alike chunks and the dreamed wiki wins clearly.

  • Caveats: synthetic data, one generator, one run each. This supports "the idea works under these conditions", not "it will help your project". Reproduce with node eval/run.js --scenario all --qa (see eval/README.md). Cost of the scale dream: about 1M tokens (GPT) and 1.9M (Gemini).

Install

npx archivum-cli init

init detects Claude Code (~/.claude) and Codex. Claude Code gets SessionStart and Stop hooks in ~/.claude/settings.json (backed up first, existing hooks kept) plus the MCP server; Codex gets codex mcp add archivum -- npx -y archivum-cli mcp. archivum doctor checks the result. Requires Node 22+.

Use it from your agent

Archivum is an MCP server (npx -y archivum-cli mcp, stdio) with 13 tools (remember, recall, forget, context, list_notes, read_document, search_documents, list_documents, related_documents, document_history, memory_status, list_proposals, show_proposal) and an archivum://context resource. Verified with the official MCP SDK client and with omp; not yet in other clients.

Client

Setup

Claude Code

npx archivum-cli init (hooks + MCP), or the plugin below

Codex

npx archivum-cli init, or codex mcp add archivum -- npx -y archivum-cli mcp

Cursor

add to .cursor/mcp.json: {"mcpServers":{"archivum":{"command":"npx","args":["-y","archivum-cli","mcp"]}}}

anything else

run npx -y archivum-cli mcp as a stdio MCP server

As an agent skill or plugin (from this repository)

Where

What

skills/archivum/SKILL.md

the skill: when to recall, what to remember, what never to save, why dreaming needs the user's say-so. Works with any tool that reads SKILL.md folders, e.g. npx skills add tryarchivum/archivum

.claude-plugin/

Claude Code plugin and marketplace manifests

.codex-plugin/

Codex plugin manifest

.cursor-plugin/

Cursor plugin manifest (skill only; add the MCP server as in the table)

The skill carries instructions; the tools come from the MCP server. The manifests follow the public format used by other plugins and have not been installed in Claude Code, Codex or Cursor yet. The MCP command in them (npx -y archivum-cli@0.2.2 mcp) was run from the registry.

Everyday commands

archivum remember "text"      archivum recall "query" [--limit N]
archivum context              archivum status
archivum log                  # append a transcript from JSON (agents without hooks)
archivum import omp --all     # import omp sessions
archivum dream                # estimate, confirm, then propose wiki changes
archivum dream --since DATE --max-inputs N   # dream fewer inputs
archivum dream --if-due --yes # for cron: only when enough is pending, idle and past cooldown
archivum doctor [--json]      # read-only health check (PASS/WARN/FAIL, exit 1 on FAIL)
archivum proposals            archivum diff [id]
archivum apply [id]           archivum reject [id]
archivum history [path]       archivum restore <path> [--version N]
archivum retention [--days 30]
archivum mcp                  archivum hook session-start|stop

Dreaming reads its model from the environment: ARCHIVUM_LLM_PROVIDER (anthropic, the default, or openai), ARCHIVUM_LLM_API_KEY, ARCHIVUM_LLM_BASE_URL, ARCHIVUM_ANALYZER_MODEL, ARCHIVUM_ORGANIZER_MODEL. Data lives in ~/.archivum (or $ARCHIVUM_HOME), one folder per space. Full reference: packages/cli/README.md and the docs page at /docs/.

Speed (2000 notes + 400 wiki pages, Windows): context 146 ms, status 155 ms, remember 156 ms, recall 732 ms.

Safety, briefly

  • Secrets matching known patterns are scrubbed on every write (fuzz-tested); pattern-based, so not a guarantee.

  • Dream agents can only read and edit documents. They never write the live wiki; apply does, and only if the live file still matches what the dream started from.

  • Transcripts are treated as untrusted data. The eval includes an injection scenario that passed on GPT-5.6 luna.

  • Threat model: SECURITY.md.

FAQ

Does anything leave my machine? Only the dream's calls to the LLM provider you configured. There is no Archivum server, account or telemetry.

Why not embeddings? BM25 plus an index and links is enough for a small wiki, needs no model download and is debuggable. It is a deliberate bet, and recall quality on very large stores is unproven.

How much does a dream cost? It prints an estimate first and refuses to exceed --budget. Roughly 20k to 30k tokens per short session; one noisy 48-session history was about 1M tokens. Use --since and --max-inputs for big backlogs.

Can it ruin my notes? A dream never edits the live wiki; you review a diff. Every applied write is a version you can restore.

Does it work with my agent? Any MCP client in principle. See the table above for what has actually been tested.

Is it ready for production? No. It is a beta: honest state and gaps are in Known limits.

Repository layout

  • packages/core: archivum-core, the isomorphic library (BM25 search, in-memory wiki, diffs, secret scrubber, the dream engine with Anthropic and OpenAI-compatible adapters). No node: imports.

  • packages/cli: archivum-cli, the CLI, MCP server and Claude Code hooks. Node built-ins only. Full reference in packages/cli/README.md.

  • eval/: the synthetic evaluation harness for dreaming (eval/README.md).

  • skills/, .claude-plugin/, .codex-plugin/, .cursor-plugin/: the agent skill and plugin manifests.

Known limits

  • Not run yet: Claude Code hooks in a real Claude Code session, the Anthropic provider against the real API, and MCP in most clients other than the official SDK client and omp.

  • No embeddings or semantic vector search, no accounts, no hosted storage.

  • Dreaming quality depends on the model you use. eval/ is a small synthetic check, not a benchmark; see its README for what it cannot show.

  • Secret scrubbing is pattern-based, not a guarantee.

  • recall reads every wiki page: about 0.7 s with 2000 notes and 400 pages.

Develop and test

npm install
npm test                       # core, cli and eval tests, no network
node eval/run.js --baseline --scenario all   # offline eval scores, no key needed

Licence

MIT, see LICENSE.md.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides coding agents with persistent local memory by exposing tools to save, search, and retrieve decisions, bugs, and context as Markdown with hybrid keyword and semantic search.
      4
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables multiple AI agents to share a locally controlled long-term knowledge base of Markdown notes, allowing them to retrieve, add, update, and remove preferences, decisions, and experiences. It supports cross-agent recall and version-aware changes while keeping the notes readable and editable outside the agent.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to search, retrieve, save, forget and give feedback on plain-Markdown memories that carry sources, dates and trust levels, while holding agent-written memories in a human review queue. Also supports session handoffs, entity and topic lookup, and audit history so learned context persists and stays verifiable.
      106 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding agents to persist and recall knowledge across sessions as atomic markdown cards with bidirectional wiki-links, exposed through 12 tools for searching, reading, writing, linking, archiving, and organizing memories in a shared local directory. Requires no vector database or embeddings, and optionally syncs cards across devices via git.
      9 npm
      ISC