Development Setup

Prerequisites

Tool	Version	Notes
Rust	1.88+	Pinned via `rust-toolchain` in the repo root
Node.js	20+	For the dashboard frontend
pnpm	latest	Dashboard package manager
protobuf-compiler	—	Required by Raft transport build steps
cmake	—	Required by some native dependencies
libclang-dev	—	Required by `bindgen` on Linux

macOS

brew install protobuf cmake node
npm i -g pnpm
rustup install 1.88.0

Ubuntu / Debian

sudo apt install -y protobuf-compiler cmake libclang-dev
npm i -g pnpm
rustup install 1.88.0

Clone and build

git clone https://github.com/ai-akashic/Memorose.git
cd Memorose
cargo build

The workspace contains four crates: memorose-common, memorose-core, memorose-server, and memorose-gateway. For the dashboard frontend:

cd dashboard
pnpm install
pnpm build

Configuration

Copy the example environment file:

cp .env.example .env

At minimum, set one provider key and model names:

GOOGLE_API_KEY=your_key_here
LLM_MODEL=gemini-2.0-flash
EMBEDDING_MODEL=text-embedding-004

If you want to force the provider via env, prefer:

MEMOROSE__LLM__PROVIDER=Gemini

Or:

MEMOROSE__LLM__PROVIDER=OpenAI
OPENAI_API_KEY=your_key_here

Create config.toml manually using the current schema in crates/memorose-common/src/config.rs. Do not rely on config.example.toml as a fully current template.

Running locally

Standalone mode

The fastest way to get one local node running:

./scripts/start_cluster.sh start --mode standalone

This starts one API node on port 3000 and the dashboard on 3100.

Local cluster mode

To simulate a 3-node local Raft cluster:

./scripts/start_cluster.sh start --clean --build

Other helper commands

./scripts/start_cluster.sh status
./scripts/start_cluster.sh stop
./scripts/start_cluster.sh restart --clean

Dashboard dev server

For frontend development with hot reload:

cd dashboard
pnpm dev

Ports

Service	Port	Notes
API (node 1)	3000	Primary local node
API (node 2)	3001	Local cluster mode only
API (node 3)	3002	Local cluster mode only
Gateway	8080	`docker-compose.yml` only
Dashboard	3100	Next.js frontend
Raft	5001–5003	Internal consensus traffic

Docker

A docker-compose.yml is provided:

docker compose up

This starts the gateway, two server nodes, and the dashboard.

When running the dashboard in Docker, set DASHBOARD_API_ORIGIN to the backend container URL, for example http://memorose-node-0:3000. Otherwise the dashboard will try to call 127.0.0.1:3000 inside its own container and fail.

​Development Setup

​Prerequisites

​macOS

​Ubuntu / Debian

​Clone and build

​Configuration

​Running locally

​Standalone mode

​Local cluster mode

​Other helper commands

​Dashboard dev server

​Ports

​Docker

Development Setup

Prerequisites

macOS

Ubuntu / Debian

Clone and build

Configuration

Running locally

Standalone mode

Local cluster mode

Other helper commands

Dashboard dev server

Ports

Docker