# Installation

## Status and Requirements

`agentic-remem` has not been published to npm. Install from a source checkout.

Required for all modes:

- Node.js 22 or newer;
- npm; and
- OpenCode v2 beta `0.0.0-beta-18743` for the primary adapter, or OpenCode `1.18.26` for the isolated
  compatibility adapter.

Managed mode also requires a running Docker engine with Docker Compose. External mode requires a
PostgreSQL server with pgvector 0.8 or newer and host `pg_dump`/`pg_restore` binaries for CLI backup and restore.
The tested database image is `pgvector/pgvector:0.8.1-pg16`.

## Build the Source Checkout

From the repository root:

```sh
npm ci
npm run build
npm link
```

`npm link` exposes the local `remem` executable. If you do not want a global link, replace `remem` in
every example with `node /absolute/path/to/remem/dist/cli.js`.

## Managed Installation

```sh
remem init --mode managed
remem doctor
```

Initialization:

1. checks Docker and Compose;
2. creates protected config/data/backup directories;
3. selects an available port starting at `54329`;
4. creates a generated database password and protected Compose files;
5. starts `pgvector/pgvector:0.8.1-pg16` on `127.0.0.1` only;
6. applies schema migrations through version 4; and
7. runs doctor checks.

`remem init` selects the `bge-small-en-v1.5` neural embedding model by
default for both `--mode managed` and `--mode external`, and prints a
warning that its weights (~30MB) download once, on first use. See
[`docs/embeddings.md#if-the-download-is-blocked-firewalls-air-gapped-environments`](./embeddings.md#if-the-download-is-blocked-firewalls-air-gapped-environments)
for offline/air-gapped fallback options, and `remem doctor` to check backlog status.

Choose a starting port explicitly when needed:

```sh
remem init --mode managed --port 55432
```

The CLI tries that port and up to the next 99 loopback ports. Re-running `remem init` is idempotent
for an existing valid configuration: it starts managed storage if needed and applies pending
migrations.

## External PostgreSQL

Create an empty database and grant the Remem role enough privilege to create the `vector` extension,
the `remem` schema, tables, and indexes. Then initialize with an environment variable:

```sh
REMEM_DATABASE_URL='postgresql://remem:password@db.example/remem?sslmode=require' \
  remem init --mode external
remem doctor
```

The direct flag also works but can expose credentials in shell history or process listings:

```sh
remem init --mode external --database-url 'postgresql://remem:password@db.example/remem'
```

External mode does not provision, start, stop, or reset PostgreSQL. TLS, certificates, server
updates, availability, physical recovery, and backup scheduling remain operator responsibilities.

## Configure OpenCode v2

`remem init --opencode` configures the current v2 adapter. Source users should add the built package-root entry to OpenCode's `plugins` list:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugins": [
    {
      "package": "file:///absolute/path/to/remem/dist"
    }
  ]
}
```

With no inline provider options, the plugin reads the application config created by `remem init`.
Restart OpenCode after editing its configuration.

`remem init --opencode` adds the bare package string `agentic-remem`. Because the package is not
published, use that flag only when your OpenCode installation can already resolve a local package
with that name. The explicit file URL above is the reliable source-checkout path.

## Configure OpenCode v1.18.27

Use `remem init --opencode-v1` for OpenCode v1. It writes the legacy singular `plugin` key,
not v2's `plugins` key. Once the package is published, OpenCode resolves its `./server` export
from the package-root specifier:

```json
{
  "plugin": ["agentic-remem"]
}
```

For a source checkout, point directly at the built v1 server module instead:

```json
{
  "plugin": ["file:///absolute/path/to/remem/dist/server.js"]
}
```

The v1 adapter is tested against OpenCode `1.18.27`. It has a weaker trust boundary than v2:
recalled memory is appended to `UserMessage.system`. Treat v1 as compatibility support and prefer
v2 where available. See [OpenCode integration](opencode-integration.md).

## Platform Locations

| Platform | Configuration directory                               | Data directory                                           |
| -------- | ----------------------------------------------------- | -------------------------------------------------------- |
| Linux    | `$XDG_CONFIG_HOME/remem`, otherwise `~/.config/remem` | `$XDG_DATA_HOME/remem`, otherwise `~/.local/share/remem` |
| macOS    | `~/Library/Application Support/Remem`                 | `~/Library/Application Support/Remem/data`               |
| Windows  | `%APPDATA%\Remem`                                     | `%LOCALAPPDATA%\Remem`                                   |

The configuration file is `config.json`; managed mode also creates `compose.yaml` and `.env` in the
configuration directory. Backups default to `backups/` under the data directory.

Override locations with `REMEM_CONFIG_DIR`, `REMEM_DATA_DIR`, or the full config file path
`REMEM_CONFIG`. See [Configuration](configuration.md) for precedence and security details.

## Verify the Installation

```sh
remem status
remem doctor
```

`status` and `doctor` currently run the same check suite:

- config and managed credential permissions;
- Docker and Compose availability in managed mode;
- managed container health or external ownership status;
- writable data directory;
- configured provider health;
- PostgreSQL connectivity and version;
- pgvector extension presence;
- pending schema migrations;
- database write access;
- embedding model ID and 384 dimensions; and
- whether an OpenCode config contains `agentic-remem`.

The OpenCode check is a string-presence check for `agentic-remem`. It cannot prove that the beta host
loaded the plugin or that a local file URL is correct. A source file URL whose path does not contain
that exact package name can produce a warning even when configured correctly.

## Upgrade a Source Checkout

After updating source:

```sh
npm ci
npm run build
remem backup
remem migrate
remem doctor
```

Automated pre-upgrade backups are not implemented. Keep the generated config and database backup
separate from the source checkout.