---
title: "Getting started"
description: "Install a repository build of Amnesia, enable it in Obsidian, open an EPUB or PDF, and verify the public API."
canonical: https://amnesia-docs.pages.dev/getting-started/installation/
source: "src/content/docs/getting-started/installation.md"
---

# Getting started

Amnesia is an Obsidian reader for EPUB and PDF files. The plugin manifest currently requires
**Obsidian 1.0.0 or later** and is not marked desktop-only.

You can start with local files only. The optional Amnesia server is disabled by default and is not
required to open an EPUB or PDF that is already in your vault.

## Build the plugin

For a repository build, the workspace requires Node.js 18+ and pnpm 8+. From the repository root:

```bash
pnpm install
cd apps/amnesia
pnpm build:no-server
```

`build:no-server` performs the production TypeScript/esbuild build without requiring the optional
Rust server binary. The build writes the plugin runtime and its worker/WASM assets to:

```text
apps/amnesia/temp/vault/.obsidian/plugins/amnesia/
```

The source `manifest.json` lives in `apps/amnesia/`. Install the complete generated directory plus
that manifest in the target vault's plugin directory:

```text
<your-vault>/.obsidian/plugins/amnesia/
```

At minimum, keep `manifest.json`, `main.js`, `styles.css`, and the generated worker/WASM assets
together. Do not copy only `main.js`; PDF/document rendering depends on assets emitted beside the
bundle.

:::tip[Building with the bundled server]
`pnpm build` uses the same plugin build but also attempts to compile and package `amnesia-server` when
Rust/Cargo is available. Use that path only when you need the server-backed features.
:::

## Enable Amnesia in Obsidian

1. Restart or reload Obsidian after placing the plugin files in the vault.
2. Open **Settings → Community plugins**.
3. Enable **Amnesia**.
4. Open **Settings → Amnesia** to review reading, library, sync, notes, and advanced options.

The local books-folder setting defaults to `Books`. Server integration starts disabled, so a basic
local-reading setup does not need a server URL.

## Open your first book

Place an `.epub` or `.pdf` file in the vault and open it from Obsidian's file explorer.

Amnesia explicitly registers `.epub` with its reader view and routes `.pdf` files to that same reader
surface instead of Obsidian's built-in PDF view. You do not need to run a library scan before opening
a file directly.

Once a document is open, Amnesia can keep source locations alongside highlights, bookmarks, notes,
and links so those records can return to the reader context later.

## Verify the public API

When plugin initialization completes, Amnesia creates API version **1.0.0** and exposes it through the
plugin instance and `window.Amnesia`.

For a script environment such as Templater or QuickAdd:

```js
const api = window.Amnesia;
console.log(api.version); // "1.0.0"
```

For another Obsidian plugin:

```ts
const api = this.app.plugins.plugins['amnesia']?.api;
if (!api) throw new Error('Amnesia is not loaded');
```

The current root exposes reactive state stores, domain command facades, typed events and hooks, UI
registries, and `connect()` for capability-scoped integrations:

```js
api.state.reader;
api.state.library;
api.state.highlights;
api.state.bookmarks;

api.commands.reader;
api.commands.library;
api.commands.highlights;
api.commands.bookmarks;
api.commands.notes;
api.commands.links;
api.commands.mupdf;

api.events;
api.hooks;
api.ui;
```

If an integration can load before Amnesia, the plugin also emits an `amnesia:ready` workspace event
after publishing the API.

:::note[Check stability before depending on a facade]
The runtime assembles more interfaces than the set currently documented as stable. Before shipping an
integration, check the [API overview](/api/overview/) and the relevant reference page for its stability
label and runtime caveats.
:::

## Next steps

- [Connect to the API](/api/guides/connect-to-the-api/) for a capability-scoped integration.
- [Add notes and links](/api/guides/add-notes-and-links/) for source-linked annotation workflows.
- [Subscribe to events](/api/guides/subscribe-to-events/) for lifecycle-safe event handling.
- [Extract and annotate PDFs with MuPDF](/api/guides/render-with-mupdf/) for PDF primitives.

<sub>Getting-started instructions verified against the current Amnesia build configuration and plugin implementation on 2026-08-17.</sub>