Archivum
Officialby tryarchivum
README.md
<div align="center">
# 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.
[](https://www.npmjs.com/package/archivum-cli)
[](https://github.com/tryarchivum/archivum/actions/workflows/ci.yml)
[](LICENSE.md)
[](#install)
[](#use-it-from-your-agent)
[](packages/core/package.json)
[Bahasa Indonesia](README.id.md) · [Quick start](#quick-start) · [How it works](#how-it-works) · [Does it help?](#does-it-actually-help) · [Use it from your agent](#use-it-from-your-agent) · [FAQ](#faq) · [Docs](#project-documents)
<code>npx archivum-cli init</code>
</div>
<p align="center"><img src="docs/assets/demo.svg" alt="archivum remember, recall and status in a terminal" width="720"></p>
---
> [!NOTE]
> Beta. Everything below marked "verified" was run; [Known limits](#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](https://www.anthropic.com/research/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`.
## Quick start
```bash
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):
```bash
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
```mermaid
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](eval/README.md)). Cost of the scale dream: about 1M tokens (GPT) and 1.9M (Gemini).
## Install
```bash
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](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](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](#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](packages/cli/README.md).
- `eval/`: the synthetic evaluation harness for dreaming ([eval/README.md](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](LICENSE.md).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues