> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memorose.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install and configure a local Memorose instance against the current runtime.

# Installation

Memorose runs as a Rust API server plus a separate dashboard UI.

## Prerequisites

* Rust toolchain
* Node.js and `pnpm` for the dashboard
* An LLM provider key for embeddings and consolidation
* Optional: `jq` for command-line examples

## Clone the repository

```bash theme={null}
git clone https://github.com/ai-akashic/Memorose.git
cd Memorose
```

## Environment setup

Copy the example environment file:

```bash theme={null}
cp .env.example .env
```

At minimum, set a provider key plus model names:

```bash theme={null}
GOOGLE_API_KEY=your_google_api_key_here
LLM_MODEL=gemini-2.0-flash
EMBEDDING_MODEL=text-embedding-004
```

If you want to force the provider through env overrides, prefer:

```bash theme={null}
MEMOROSE__LLM__PROVIDER=Gemini
```

Or:

```bash theme={null}
MEMOROSE__LLM__PROVIDER=OpenAI
OPENAI_API_KEY=your_openai_api_key_here
```

To avoid the default dashboard password warning, also set:

```bash theme={null}
DASHBOARD_ADMIN_PASSWORD=change-me
```

## Configuration

Create `config.toml` yourself using the current schema from `crates/memorose-common/src/config.rs`, or start from `config.example.toml` / `config.toml.example` and keep `config.rs` as the final source of truth.

A minimal starting point is:

```toml theme={null}
[llm]
provider = "Gemini"
model = "gemini-2.0-flash"
embedding_model = "text-embedding-004"

[storage]
root_dir = "./data/node-1"

[raft]
node_id = 1
raft_addr = "127.0.0.1:5001"
heartbeat_interval_ms = 500
election_timeout_min_ms = 1500
election_timeout_max_ms = 3000
snapshot_logs = 1000000
auto_initialize = true

[worker]
llm_concurrency = 5
decay_interval_secs = 60
prune_threshold = 0.1
consolidation_interval_ms = 1000
community_interval_ms = 1000
insight_interval_ms = 30000
enable_auto_planner = true
enable_task_reflection = true
auto_link_similarity_threshold = 0.6
tick_interval_ms = 100

[reranker]
type = "weighted"
```

To enable internal model-based arbitration, add a reranker block:

```toml theme={null}
[reranker]
type = "arbitrator"
model = "gemini-3.1-flash-lite-preview"
max_candidates = 32
fallback_to_weighted = true
```

## Start the stack

Recommended local startup:

```bash theme={null}
./scripts/start_cluster.sh start --clean --build
```

This starts backend nodes on `3000`, `3001`, and `3002` in local cluster mode, plus the dashboard UI on `3100`.

If you want a single local node:

```bash theme={null}
./scripts/start_cluster.sh start --mode standalone
```

## Manual server startup

If you only want the API server:

```bash theme={null}
cargo run --release -p memorose-server
```

## Docker reranker configuration

The Docker image starts the API server on `3000` and the dashboard on `3100`. Reranker mode is still configured by the same `MEMOROSE__*` environment variables:

```bash theme={null}
docker run -d \
  --name memorose \
  -p 3000:3000 \
  -p 3100:3100 \
  -v memorose_data:/app/data \
  -e GOOGLE_API_KEY="your_google_api_key_here" \
  -e MEMOROSE__LLM__MODEL="gemini-3.1-flash-lite-preview" \
  -e MEMOROSE__LLM__EMBEDDING_MODEL="gemini-embedding-2-preview" \
  -e MEMOROSE__RERANKER__TYPE="arbitrator" \
  -e MEMOROSE__RERANKER__MODEL="gemini-3.1-flash-lite-preview" \
  -e MEMOROSE__RERANKER__MAX_CANDIDATES="32" \
  -e MEMOROSE__RERANKER__FALLBACK_TO_WEIGHTED="true" \
  dylan2024/memorose:latest
```

## Verify the installation

Check the root endpoint:

```bash theme={null}
curl http://127.0.0.1:3000/
```

Expected response:

```text theme={null}
Memorose is running.
```

## Dashboard

* Dashboard UI: `http://127.0.0.1:3100/dashboard`
* API redirect: `http://127.0.0.1:3000/dashboard`
* Default login: `admin` / `admin`

On first login, the response may include `must_change_password: true` until you set a new password.

<Warning>
  If you deploy the dashboard using your own `docker-compose.yml` or `docker run`, you must set `DASHBOARD_API_ORIGIN` on the dashboard container to point at the backend API, for example `DASHBOARD_API_ORIGIN=http://memorose-node-0:3000`. Otherwise login and proxied dashboard requests will fail with `connect ECONNREFUSED 127.0.0.1:3000`.
</Warning>