project · reverie · getting started

reverie — getting started

Reverie ships as a daemon you run locally and talk to over HTTP — or, from a coding agent, over MCP. This page takes a clean box to a running reveried and your first memory write and read in about five minutes. It assumes nothing beyond a Rust toolchain.

Install

There is one supported path: clone the repo and run the one-shot installer. On a box with cargo and rustc already present, it builds the workspace, copies the binaries into ~/.local/bin/, installs a systemd --user unit, and starts the daemon — everything inside $HOME, no sudo.

git clone [email protected]:cerebral-work/reverie.git
cd reverie
scripts/install-reverie.sh

That installs the reveried daemon, the cortex operator console, and the benchmark and tracee binaries into ~/.local/bin/. The installer is idempotent — re-run it after a git pull to upgrade in place; it stops the daemon, swaps the binary, restarts, and re-checks /health.

Prerequisites

Rust 1.94+ — required. curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh.
git — required.
redis-server — recommended, not required. The daemon’s coord paths degrade gracefully to filesystem-only when Redis is missing; HTTP search, save, context, and the dream cycle all still work without it.
systemd user bus — recommended, for auto-restart. Pass --skip-systemd to run reveried by hand instead.

Useful installer flags: --skip-redis-check (silence the Redis probe), --skip-systemd (don’t install the user unit), --skip-smoke (don’t curl /health after start), and --release-profile=dev (faster compile, slower runtime — fine for ephemeral smoke hosts, not for shipping). --help lists the full set.

Run reveried

With the systemd unit installed, the installer already started the daemon. It listens on 127.0.0.1:7437. Confirm it is live before doing anything else:

curl -s http://127.0.0.1:7437/health
# → {"status":"ok","service":"engram","version":"0.9.13"}

The systemd controls, when you need them:

systemctl --user status reveried     # is it up?
systemctl --user restart reveried    # bounce it
journalctl --user -u reveried -f     # follow the log

If you skipped systemd, run the binary in the foreground instead — ~/.local/bin/reveried — and it serves the same surface on the same port. The sqlite memory store is created on first start at ~/.engram/engram.db; if /health never answers, the daemon log is the first place to look (port already in use and a malformed ~/.engram/config.toml are the usual causes).

Basic memory ops

A “memory” in reverie is an observation — a typed, titled note scoped to a project. The three operations you reach for first are save, search, and context. Each has an HTTP route and an equivalent MCP tool; the MCP tools call the same store code paths as the HTTP routes, so the two are interchangeable.

Over HTTP

Save an observation. A write needs a session id, a type, a title, and content; project and scope are optional (scope defaults to project; the alternative is personal):

curl -s -X POST http://127.0.0.1:7437/observations \
  -H 'Content-Type: application/json' \
  -d '{
        "session_id": "manual-save-demo",
        "type":       "decision",
        "title":      "Use bun for the site build",
        "content":    "What: standardized on bun. Why: lockfile + speed.",
        "project":    "demo"
      }'
# → {"id":1,"status":"saved"}

Search over what you’ve saved. q is the only required parameter; type, project, scope, and limit (default 10) narrow the result. Search is full-text (FTS5, bm25-ranked):

curl -s 'http://127.0.0.1:7437/search?q=bun+build&project=demo'
# → [{ ...observation..., "rank": -1.23 }]

Context returns a ready-to-inject markdown blob — recent sessions, observations, and prompts for a project — which is exactly what a harness loads at the start of a session:

curl -s 'http://127.0.0.1:7437/context?project=demo&limit=15'
# → {"context":"## Recent Observations\n..."}

One sharp edge worth knowing: compact on /context is parsed strictly (1|0|t|f|true|false). ?compact=yes is silently ignored rather than rejected — use ?compact=true.

Over MCP

From a coding agent, the same operations are MCP tools rather than curl calls. The default --tools=agent profile exposes thirteen; the three that mirror the HTTP ops above are:

mem_save — title and content required; type, project, scope, and an opt-in topic_key for upserts. Same code path as POST /observations.
mem_search — query required; type, project, scope, limit (default 10, max 20) to narrow. Returns formatted hits with previews and an instruction to call mem_get_observation for a full body.
mem_context — project, scope, limit (default 20). Returns the same context blob as GET /context; this is what the SessionStart hook injects into the agent’s system reminder.

A topic_key (for example architecture/auth-model) turns a save into an upsert — the next mem_save under the same key revises the existing observation instead of duplicating it, which is how reverie avoids the duplicate-staleness failure mode.

Where to go next

These three ops are the floor, not the ceiling. cortex is the operator console that drives the daemon and the agent mesh on top of this surface — session bring-up, the live dashboard, the operator gate, and a manual cortex dream trigger to kick the offline consolidation cycle reverie runs over what you’ve saved. The placement model, the derivability gate, and the retrieval stack that make those saves worth keeping are described on the reverie page.

Status

Proprietary. Copyright © 2026 Christian M. Todie / cerebral.work — all rights reserved. The install path and HTTP/MCP surface described here track reverie as it shapes up toward v1.0; routes and flags will move until then. For commercial licensing, embedded use, or evaluation access, [email protected].

← back to reverie Meet cortex →