Getting started

Memra holds what Claude forgets.

Memra is a memory and orchestration layer for Claude Code. One session ends — the next already knows what you were up to. This documentation shows you how to get productive in under 60 seconds.

Installation

Memra runs on macOS, Linux and Windows. A single line.

curl -fsSL https://memra.ch/install | bash

The installer places the memra binary in ~/.local/bin (overridable via MEMRA_INSTALL_DIR) and warns if that directory is not on your PATH.

Quickstart

Three commands. Sixty seconds.

1) Init in the project

cd ~/projects/my-app
memra init

Creates or extends CLAUDE.md with the MEMRA instructions and registers the project in the cloud. The project config lives in ./.shiva/config.json.

2) Remember something

memra remember "API uses Bearer tokens, not basic auth" --category solution

3) Recall in your next session

memra search auth

When you start a new Claude Code session, Memra automatically reads relevant memories into context — no manual reset needed. One-time setup: memra hook install — installs the Claude Code hooks that handle context injection.

Your Claude API Key

Memra runs on your Anthropic API key — you bring the intelligence, we provide the layer beneath. No third-party subscription, no vendor lock-in.

Store your key

The easiest way is the dashboard — your key is stored encrypted there and never logged as plaintext:

• → Dashboard → Secrets → create ANTHROPIC_API_KEY

Or via CLI:

memra secrets add ANTHROPIC_API_KEY "sk-ant-..."               # global ist Default
memra secrets add ANTHROPIC_API_KEY "sk-ant-..." -p <projekt>  # nur ein Projekt

Cloud proxy (memra.ch)

When you run workers on memra.ch (cloud mode), your API key never enters the worker container. Memra keeps the key server-side and proxies the Anthropic calls — the worker only ever sees an anonymized connection.

How MEMRA works

MEMRA is a control plane, not a compute plane. Your Claude Code sessions, your workers and your Anthropic key always run on your own machine. The cloud (api.memra.ch) only stores metadata, coordinates dispatches and serves the dashboard.

The six connections between them:

• Memory & session sync — your memories & sessions persist across machines (memra sync).
• Dispatch — the cloud queues a job, your Local Runner pulls it and runs Claude on your machine.
• Orchestration — one session conducts others, purely locally via ~/.memra/control.
• Session sync — see local sessions online; continuing the chat is 2FA/passkey-secured.
• Auth — 1 h access + 30-day refresh cookie, 2FA/passkey.
• Studio (local) — the same dashboard directly against your machine, entirely without the cloud.

MEMRA's surfaces

You drive MEMRA through four surfaces — all run locally in your terminal (the cloud dashboard at memra.ch is the fifth, for on the go). Each one below is recorded live, with real commands and real output.

Memory

Memra memories are categorized text snippets with search and tags. Categories help Memra know when a memory is relevant.

Categories

• stack — tech-stack decisions (Node 20, Postgres 15, …)
• config — ports, env vars, setup specifics
• solution — problems you've already solved
• convention — code conventions in the project
• intent — what you plan to do next
• correction — user corrects an assumption
• architecture — project structure, modules, patterns
• env — production vs development specifics

Memory Scoping

Searches are project-scoped by default — you only see memories from the current project. That prevents solutions from project A from unintentionally showing up in project B (memory bleed).

memra search "auth"                      # nur aktuelles Projekt (default)
memra search "auth" --all                # projektübergreifend
memra search "auth" --project memra-web  # bestimmtes Projekt explizit

Writing memories is always project-scoped — the project derives from the current directory. Global memories (across all projects) require --global:

memra remember "shared convention" --global  # in jedem Projekt sichtbar
memra remember "project-specific fact"       # nur in diesem Projekt

Search

Memories can be searched by full text or category:

memra search "auth bearer"
memra search "" --category solution
memra search "" --category convention --project memra-web

Management

memra search ""                  # alle Memories (project-scoped)
memra search "" --category solution --limit 20
memra forget <key>               # Memory löschen
memra export --backup -o backup  # Backup-Archiv erstellen

Sessions

A session is the bridge between two Claude Code conversations. For each session Memra records: what happened, which memories were created, which files were touched.

Starting a session

memra start memra-web      # Session im Projekt starten (-n für neue)
memra conductor            # Orchestration-Board öffnen
memra resume <session-id>  # vorige Session fortsetzen

Status & History

memra sessions                      # aktive + paused Sessions
memra sessions active               # nur live Sessions
memra sessions --project memra-web  # filter by project

Orchestration

You can use any Claude Code session as a conductor — it dispatches sub-tasks to worker sessions in parallel. Memra manages: budget caps, permission gates, memory sharing between workers.

The conductor pattern

A conductor is a regular Claude Code session that attaches workers with memra worker spawn/attach and thereby becomes a conductor. It can spawn workers, dispatch directives, and wait for responses — all without blocking its own context window.

The typical flow:

1. The conductor spawns a worker (a new Claude Code subprocess).
2. The directive is dispatched asynchronously in the background — the conductor is free again immediately.
3. The conductor arms a monitor listener and waits for the result pingback.
4. The worker returns diff stats + status, and the conductor moves on to the next task.

Dispatching workers

# Non-blocking dispatch — Antwort landet in der Inbox (bevorzugt gegenüber send)
memra worker dispatch frontend "refit landing nav with new logo"

# Synchron senden (blockt bis der Worker fertig ist)
memra worker send frontend "refit landing nav with new logo"

# parallel dispatch an alle Aliases gleichzeitig
memra worker fanout frontend,backend "rename MEMRA references to Memra"

# Read-only mode (kein Write) — für Audits: Scout, zählt nicht gegen den Worker-Cap
memra worker send --read-only frontend "check for hardcoded secrets"
memra worker scout "check for hardcoded secrets"

# Ergebnisse der Worker lesen
memra worker inbox
memra worker brief

# Orchestrierungs-Board öffnen
memra conductor

Budget caps

Memra automatically sets a budget per conversation. Default: 20 dispatches. Set it via:

memra control budget 50

Web-Conductor

Instead of the CLI you can open a conductor in the browser:

• → Dashboard / Conductor — chat UI with multi-project picker
• Multi-project orchestration via a single conversation
• Live worker status, progress bars, diff stats

Workers

Workers are separate Claude Code subprocesses with their own context. You dispatch directives — they return diff stats + status. Up to 5 workers in parallel per project (system-wide limit configurable, default 10).

Worker management

memra worker spawn <project> "directive"  # neuen Worker in einem Projekt starten — der Kern-Befehl
memra worker list --json                  # alle Worker-Sessions
memra worker attach <id>                  # bestehende Session als Worker anbinden
memra worker detach <alias>               # Worker freigeben (Session läuft weiter)
memra worker status                       # aktuelle Worker + Budget zeigen

KV (shared blackboard)

Workers can communicate through a shared key-value store:

memra worker kv set deploy version v1.2.3
memra worker kv get deploy version
memra worker kv list deploy

Hidden Gems

Three commands almost nobody knows — yet used daily in complex orchestrations.

1. Worker KV — persistent blackboard

memra worker kv is a project-wide key-value store for cross-worker aggregation. Workers write independently into the same namespace — the conductor reads the sum. Ideal when several workers write audit findings in parallel and you want to merge everything at the end.

# Worker A schreibt seinen Befund
memra worker kv set audit worker-1 "no issues found"

# Worker B schreibt parallel (eigener Prozess)
memra worker kv set audit worker-2 "3 warnings in auth.ts"

# Dirigent liest alle Einträge im Namespace
memra worker kv list audit

# Gezielter Abruf
memra worker kv get audit worker-2

• When to useParallel workflows where workers accumulate results independently (audits, test reports, feature scans).
• When not toFor direct session-to-session communication, memra peer brief is better — visible instantly at the next user prompt.

2. Worker Consolidate — automatic summary

memra worker consolidate <namespace> has a fast Haiku worker iterate over all entries of a KV namespace and generate a compact summary. Instead of reading 8 worker reports yourself, you get a 5-line summary in seconds.

# Nach Parallel-Fanout: alle Workers haben in "audit" geschrieben
memra worker consolidate audit

# Nur einen Eintrag zusammenfassen
memra worker consolidate audit:worker-2

# Digest zurück in KV schreiben
memra worker consolidate audit --into audit:summary

• When to useAfter a fanout where workers write findings into a namespace — you want a summary without reading manually.
• When not toFor just a few (<3) entries, a manual memra worker kv list is enough.

3. Workflow gears in the background

memra workflow run <gear> --background starts a built-in workflow gear (integration-check, debug, build, tool-check) asynchronously — the conductor is immediately free again and receives the result as an inbox briefing when the gear finishes.

# Integration-Check im Hintergrund starten
memra workflow run integration-check --background

# Debug-Gear: analysiert Errors + Logs, schreibt Report
memra workflow run debug --background

memra workflow runs           # laufende Gear-Runs anzeigen
memra workflow install-gears  # built-in Gears installieren (danach: memra workflow list)

• When to useExpensive checks (build, tests, typecheck) that you don't want to block in the conductor chat.
• When not toFor simple one-off inspections, memra worker send --read-only is enough — for audits use memra worker scout (read-only investigator, doesn't count against the worker cap).

CLI Reference

All commands accept --help for detailed options. Many commands accept --json; the only global flag is --debug.

memra init

Initializes Memra in the current project — creates or extends CLAUDE.md with the MEMRA instructions and registers the project in the cloud. The project config lives in ./.shiva/config.json.

memra init                  # interaktiv (empfohlen)
memra init -d ./my-project  # anderes Verzeichnis
memra init --template api   # Template: api, frontend, cli, fullstack, library
memra init --no-sync        # nur lokal, kein Cloud-Sync

memra sync

Syncs your local Memra with the cloud — afterwards projects, memories, and sessions appear live in the dashboard at memra.ch. Prerequisite: run memra login once.

memra sync                  # aktuelles Projekt (push + pull)
memra sync -a               # ALLE Projekte synchronisieren
memra sync --push           # nur lokal → cloud
memra sync --pull           # nur cloud → lokal
memra sync -d ./my-project  # bestimmtes Verzeichnis

After the first sync, synchronization runs automatically in the background (interval via backgroundSync.intervalSec in ~/.memra/settings.json, default 60s). The "Offline" indicator in the dashboard turns green as soon as the CLI is connected and has synced.

memra remember

Saves a memory snippet. It's automatically loaded as context in future sessions of the project when relevant.

memra remember "<text>" --category <cat>
# Kategorien: solution · convention · intent · correction
#             config · stack · architecture · env

# Beispiele:
memra remember "API uses Bearer tokens" --category convention
memra remember "User wants TS, not JS"  --category correction
memra remember "Dev port 3001, DB 5432" --category config

memra remember "..." --category solution   # Projekt = aktuelles Verzeichnis

memra search

Full-text search across all memories of the project. With --all, across all projects.

memra search "authentication"        # alle Memories die "authentication" enthalten
memra search "" --category solution  # alle solution-Memories
memra search "" --limit 10           # letzte 10 Memories
memra search --all "stripe"          # über alle Projekte
memra search "" --json               # für Tooling-Integration

memra session

memra session manages sandbox snapshots — review, apply, or discard changes from a sandbox. Sessions themselves run via memra sessions / memra resume.

memra session list          # Sandbox-Sessions
memra session review <id>   # Änderungen prüfen
memra session apply <id>    # Sandbox-Änderungen übernehmen
memra session discard <id>  # verwerfen
memra sessions              # alle Sessions (Übersicht)
memra resume <id>           # weiterführen — Kontext wird re-injiziert

memra worker

Spawn workers, attach to sessions, and send directives. The foundation of the conductor pattern.

memra worker spawn <project> "directive" # neuen Worker in einem Projekt starten — der Kern-Befehl
memra worker list --json                           # alle reachable Workers
memra worker attach <sid> --alias web              # bind worker
memra worker dispatch <alias> "directive"          # non-blocking; Antwort landet in der Inbox — bevorzugt gegenüber send
memra worker send <alias> "directive"              # synchron senden (blockt)
memra worker fanout a,b "directive"                # parallel dispatch an alle Aliases gleichzeitig
memra worker send --read-only <alias> "inspect X"  # safe mode, kein write
memra worker scout "frage"                         # read-only Investigator, zählt nicht gegen den Worker-Cap
memra worker send --force <alias> "..."            # override busy-detect
memra worker request-restart <alias>               # Live-Session um Neustart bitten (Inbox-Hook-Handshake)
memra worker detach <alias>                        # Worker freigeben (Session läuft weiter)
memra worker kv set <ns> <k> <v>                   # shared blackboard
memra worker kv get <ns> <k>

memra peer

Lateral messaging between LIVE Claude Code sessions (each with its own user at the terminal). Unlike worker send, not a dispatch — but a briefing that becomes visible at the target session's next user prompt.

memra peer list                     # peers in deinem scope
memra peer brief <alias> "message"  # lateral briefing
memra peer inbox                    # eigene messages
memra peer inbox --drain            # inbox leeren nach lesen
memra peer whoami                   # sessionId + scope

memra workflow

Workflows group projects into repeatable setups (parallel, sequential, or orchestrated); shared data flows through the bridge KV.

memra workflow list               # alle workflows im Projekt
memra workflow run <name>         # manueller Trigger
memra workflow runs               # laufende Gear-Runs anzeigen
memra workflow corpus --limit 20  # letzte Gear-Runs
memra workflow create <name>      # Workflow anlegen (Projekte danach: memra workflow add <wf> <pfad>)

memra studio

Local HTTP/SSE server for the dashboard — streams audit/health/approvals live. The port is random and is printed at startup together with the URL + token.

memra studio serve  # Port zufällig; URL + Token werden ausgegeben
memra studio serve --port 8080 --token <TOKEN>
memra studio web    # lokales Web-Dashboard (Default-Port 8788)

Hooks

Memra installs its hooks directly into Claude Code — once, via memra hook install. They handle context injection at session start, command scanning, write guards and the worker inbox.

Install selectively with flags: --inbox, --post-tool-use, --stop-hook, --subagent-stop, --guard, --production-gate — or all at once with --all.

memra hook status         # installierte Hooks prüfen
memra hook install --all  # alle memra-Hooks installieren
memra hook uninstall      # entfernen

Check: memra hook status shows the installed hooks — the Hooks page in the dashboard mirrors the same state.

Workflows

Workflows group multiple projects into a repeatable setup — create, add projects, start. The parallel, sequenziell and orchestriert modes determine how the projects are processed; shared data flows through the optional bridge KV. Ready-made templates are in the library.

memra workflow create release          # Workflow anlegen
memra workflow add release ./frontend  # Projekt hinzufügen
memra workflow add release ./backend
memra workflow start release           # starten (parallel | sequenziell | orchestriert)
memra workflow library                 # Template-Library durchstöbern

Peer Briefings

Worker dispatch and peer briefing are two different modes:

Scoping

Peer briefings are limited to your own project by default (same-project). With memra peer scope open you open the scope across projects, memra peer scope project restores the default.

memra peer whoami         # eigene sessionId + scope
memra peer scope open     # Scope öffnen (projektübergreifend)
memra peer scope project  # zurück auf Default (same-project)
memra peer brief frontend "DB migration ready"
memra peer inbox          # eigene received briefings

Secrets

Encrypted key-value store for API keys and tokens. AES-GCM encrypted at rest in the cloud vault (per-value IV). Secrets are never indexed in memories or logged.

memra secrets add <KEY> "<value>"          # neuer Secret
memra secrets get <KEY>                    # Wert anzeigen (-r/--reveal für Klartext, Default maskiert)
memra secrets list                         # nur Keys, keine Values
memra secrets add <KEY> "<neuer-wert>" -f  # Wert ersetzen (kein separates rotate)
memra secrets delete <KEY>                 # permanent

Scope control

The scope is set at creation time — global (default), per project or per workflow:

memra secrets add KEY "v" --global       # Default: in allen Projekten
memra secrets add KEY "v" -p <projekt>   # nur dieses Projekt
memra secrets add KEY "v" -w <workflow>  # nur dieser Workflow

HTTP API

For tooling integration Memra offers a local HTTP API via memra studio serve. The token appears in the startup output (or via --token) and is passed as Authorization: Bearer or ?token=.

Endpoints

• GET /health — health check
• GET /api/memories · GET /api/sessions · GET /api/projects
• GET /v12/workers — worker status (+ GET /v12/workers/stream as SSE)
• POST /v12/dispatch — dispatch a directive
• GET /v12/inbox · GET /approvals · GET /settings

Example

curl -H "Authorization: Bearer <TOKEN>" http://127.0.0.1:<PORT>/api/memories

Configuration

You set the CLI config via memra config — settable keys: apiEndpoint and modelBias. Runtime settings live in ~/.memra/settings.json, the project config in ./.shiva/config.json.

Global config

memra config --list                 # alle Settings anzeigen
memra config set apiEndpoint <url>  # setzbar: apiEndpoint, modelBias
memra config set modelBias <bias>

Runtime settings (~/.memra/settings.json)

{
  "backgroundSync": { "intervalSec": 60 }
}

e.g. backgroundSync.intervalSec — interval of the background sync in seconds (default 60).

Analytics

Memra.ch uses no tracking cookie and no consent banner. Privacy-friendly analytics (Plausible or Umami) can optionally be enabled via an env var — without a set value no analytics script is loaded. To enable it, just set PUBLIC_PLAUSIBLE_DOMAIN=memra.ch (for Plausible) or PUBLIC_UMAMI_WEBSITE_ID + PUBLIC_UMAMI_SCRIPT_URL (for self-hosted Umami) in the Cloudflare Pages settings.

Troubleshooting

First thing to reach for with any problem: memra doctor — one command that checks your setup, project, hooks and cloud connection and tells you the next step.

memra: command not found

Check whether ~/.local/bin is in your PATH:

echo $PATH | tr ":" "\n" | grep .local/bin

If empty, add it to your shell profile:

echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

Cloud sync failed

Check memra doctor for a full diagnosis:

memra doctor        # vollständige Health-Check
memra doctor --fix  # versucht common Issues automatisch zu fixen
memra journal list  # Dispatch-Journal (Historie)

Worker session hangs

memra worker request-restart <alias>  # safe restart
memra worker detach <alias> --force   # force-detach