Getting started

Memra holds what Claude forgets.

Memra ist eine Memory- und Orchestration-Layer für Claude Code. Eine Session endet — die nächste weiss schon was du vorhattest. Diese Dokumentation zeigt dir, wie du in unter 60 Sekunden produktiv bist.

Installation

Memra läuft auf macOS, Linux und Windows. Eine einzige Zeile.

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

Der Installer legt das memra Binary in ~/.memra/bin und fügt es deinem PATH hinzu.

— note

Auf Apple Silicon brauchst du Rosetta 2 nicht. Auf Linux nutzt Memra ~/.local/bin falls vorhanden.

Quickstart

Drei Befehle. Sechzig Sekunden.

1) Init im Projekt

cd ~/projects/my-app
memra init

Erstellt ./.memra/ mit Memory-Stores und einer memra.config.json die du committen kannst.

2) Etwas merken

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

3) Bei der nächsten Session abrufen

memra search auth

Beim Start einer neuen Claude Code Session liest Memra automatisch relevante Memories in den Kontext — kein manueller Reset nötig.

Dein Claude API Key

Memra läuft auf deinem Anthropic-API-Key — du bringst die Intelligenz mit, wir liefern die Schicht darunter. Kein Abo bei einem Drittanbieter, kein Vendor-Lock.

Key hinterlegen

Der einfachste Weg ist das Dashboard — der Key wird dort verschlüsselt gespeichert und nie als Plaintext geloggt:

→ Dashboard → Secrets → ANTHROPIC_API_KEY anlegen

Oder per CLI:

memra secrets add ANTHROPIC_API_KEY "sk-ant-..."
# Scope "global" damit alle Projekte denselben Key nutzen
memra secrets add ANTHROPIC_API_KEY "sk-ant-..." --scope global

Cloud-Proxy (memra.ch)

Wenn du Workers auf memra.ch (Cloud-Modus) läufst, geht dein API-Key nie in den Worker-Container. Memra hält den Key serverseitig und proxied die Anthropic-Calls — der Worker sieht nur eine anonymisierte Verbindung.

— lokal vs. cloud

Lokal (memra studio serve): Key liegt in ~/.memra/secrets, AES-256-GCM verschlüsselt, verlässt dein Gerät nicht.
Cloud (memra.ch): Key liegt im Memra-Vault hinter deinem Account, wird nur per-Request genutzt und nie an den Worker-Prozess weitergegeben.

Memory

Memra Memories sind kategorisierte Text-Snippets mit Suche, Tags und (in Pro) Versionierung. Kategorien helfen Memra zu wissen wann eine Memory relevant ist.

Memory Scoping

Suchen sind standardmässig project-scoped — du siehst nur Memories des aktuellen Projekts. Das verhindert, dass Lösungen aus Projekt A ungewollt in Projekt B auftauchen (Memory-Bleed).

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

Memories schreiben ist immer project-scoped. Ohne --project wird das Projekt aus der aktuellen .memra/-Config gelesen. Globale Memories (über alle Projekte) erfordern --scope global:

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

— dirigent & scoping

Ein Dirigent der mehrere Worker über verschiedene Projekte orchestriert erbt die Memories aller seiner Worker-Projekte (Union). Er kann also für jeden Worker auf dessen Kontext zugreifen, ohne dass Projekte sich gegenseitig verschmutzen.

Suche

Memries lassen sich per Volltext oder Kategorie durchsuchen:

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

Verwaltung

memra list                              # alle Memories
memra list --category solution --limit 20
memra delete <memory-id>
memra export --format json > backup.json

— pro tip

Memra erkennt automatisch starke Sätze in Claude Code Sessions ("ich möchte X", "das funktioniert weil Y") und speichert sie. Du kannst Auto-Save in Settings → Memory deaktivieren.

Sessions

Eine Session ist die Brücke zwischen zwei Claude Code Konversationen. Memra speichert pro Session: was geschehen ist, welche Memories erzeugt wurden, welche Dateien berührt wurden.

Eine Session starten

memra start --project memra-web --branch feat/auth
memra start --as dirigent           # als Dirigent-Mode (kann Workers dispatchen)
memra start --resume <session-id>   # vorige Session fortsetzen

Status & History

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

Orchestration

In Pro und Max kannst du Memra als Dirigent benutzen — eine Claude- Code-Session dispatched Sub-Tasks an Worker-Sessions parallel. Memra managed: Budget-Caps, Permission-Gates, Memory-Sharing zwischen Workers.

Das Dirigent-Pattern

Ein Dirigent ist eine normale Claude Code Session, die mit memra start --as dirigent (oder via SessionStart-Hook) in den Orchestrierungs-Modus wechselt. Er kann Workers spawnen, Direktiven dispatchen und auf Antworten warten — alles ohne sein eigenes Kontext-Fenster zu blockieren.

Der typische Ablauf:

Dirigent spawnt einen Worker (neuer Claude Code Subprozess).
Direktive wird asynchron im Hintergrund dispatched — der Dirigent ist sofort wieder frei.
Dirigent armt einen Monitor-Listener und wartet auf das Ergebnis-Pingback.
Worker liefert Diff-Stats + Status zurück, Dirigent geht zum nächsten Task.

— warum Hintergrund?

Workers laufen detached (eigener Prozess, kein Foreground-Fork). Ein synchrones Dispatch würde den Dirigent-Chat einfrieren, bis der Worker fertig ist. Stattdessen: spawn → dispatch async → Monitor-Event kommt rein wenn Worker fertig ist.

Worker dispatchen

# Single worker dispatch
memra worker send frontend "refit landing nav with new logo"

# Parallel fanout to multiple workers (2× faster)
memra worker fanout frontend,backend "rename MEMRA references to Memra"

# Read-only mode (no edits, just inspection)
memra worker send --read-only frontend "check for hardcoded secrets"

— hidden gems

Nach einem Fanout: memra worker kv aggregiert Worker-Ergebnisse in einem Namespace, memra worker digest fasst sie automatisch zusammen, und memra workflow run --background startet Gears (integration-check, debug) ohne den Chat zu blockieren. → Hidden Gems

Budget-Caps

Memra setzt automatisch ein Budget pro Conversation. Default: 20 Dispatches. Setze via:

memra config set budget 50

Web-Conductor

Anstelle der CLI kannst du im Browser einen Dirigent öffnen:

→ Dashboard / Conductor — Chat-UI mit Multi-Project-Picker
Multi-Project Orchestration via einer einzigen Konversation
Live Worker-Status, Progress-Bars, Diff-Stats

Workers

Workers sind separate Claude-Code-Subprozesse mit eigenem Kontext. Du dispatched Direktiven — sie liefern Diff-Stats + Status zurück. Im Pro-Tier 2 parallel, im Max-Tier bis zu 8.

Worker-Verwaltung

memra worker list --json             # alle Worker-Sessions
memra worker attach <id>             # bind to existing worker
memra worker detach <alias>          # release
memra worker status                  # current attachments + budget

KV (shared blackboard)

Workers können über einen geteilten Key-Value Store kommunizieren:

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

Hidden Gems

Drei Commands die kaum jemand kennt — aber in komplexen Orchestrierungen täglich gebraucht werden.

1. Worker KV — persistenter Blackboard

memra worker kv ist ein projektweiter Key-Value Store für Cross-Worker-Aggregation. Workers schreiben unabhängig in denselben Namespace — der Dirigent liest die Summe. Ideal wenn mehrere Workers parallel Audit-Befunde schreiben und du am Ende alles zusammenführen willst.

# 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

Wann nutzen: Parallel-Workflows wo Workers unabhängig Ergebnisse akkumulieren (Audits, Test-Reports, Feature-Scans). Wann nicht: Für direkte Session-zu-Session-Kommunikation ist memra peer brief besser — sofort sichtbar beim nächsten User-Prompt.

— namespace conventions

Wähle Namespace-Namen die den Workflow beschreiben: audit-2026-05, build-results, test-coverage. KV-Einträge sind persistent bis du sie explizit löschst — nach dem Workflow den Namespace aufräumen mit memra worker kv clear <ns>.

2. Worker Digest — automatische Zusammenfassung

memra worker digest <namespace> lässt einen schnellen Haiku-Worker über alle Einträge eines KV-Namespace iterieren und eine kompakte Zusammenfassung generieren. Statt selbst 8 Worker-Reports zu lesen, bekommst du in Sekunden eine 5-Zeilen-Zusammenfassung.

# Nach Parallel-Fanout: alle workers haben in "audit" geschrieben
memra worker digest audit

# Mit spezifischer Frage an den Digest-Worker
memra worker digest audit --prompt "Welche Findings sind kritisch?"

# Digest zurück in KV schreiben (für weitere Verarbeitung)
memra worker digest audit --output-key summary

Wann nutzen: Nach einem fanout wo Workers Befunde in einen Namespace schreiben — du willst eine Zusammenfassung ohne manuell zu lesen. Wann nicht: Bei wenigen (<3) Einträgen reicht ein manuelles memra worker kv list.

3. Workflow Gears im Background

memra workflow run <gear> --background startet einen eingebauten Workflow-Gear (integration-check, debug, typecheck) asynchron — der Dirigent ist sofort wieder frei und bekommt das Ergebnis per Inbox-Briefing wenn der Gear fertig ist.

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

# Debug-Gear: analysiert Errors + Logs, schreibt Report
memra workflow run debug --background --context "auth failing in prod"

# Status des laufenden Gears prüfen
memra workflow logs integration-check --tail

# Alle verfügbaren Gears anzeigen
memra workflow gears

Wann nutzen: Teure Checks (Build, Tests, Typecheck) die du nicht im Dirigent-Chat blockieren willst. Wann nicht: Für einfache Inspektionen ohne Wiederholung reicht memra worker send --read-only.

— built-in gears

Memra liefert drei Gears out-of-the-box: integration-check (baut + testet), debug (analysiert Errors + Logs), typecheck (tsc/mypy ohne Änderungen). Eigene Gears definierst du als Workflow-YAML mit type: gear.

CLI Reference

Alle Befehle akzeptieren --help für detaillierte Optionen. Globale Flags: --json, --quiet, --verbose.

`memra init`

Initialisiert Memra im aktuellen Projekt — erstellt .memra/ Ordner mit Config, Hooks-Verzeichnis und Cloud-Sync-Anbindung.

memra init                          # interaktiv (empfohlen)
memra init --name my-project        # mit projekt-name
memra init --import memra           # bestehende Memories aus anderer CLI importieren
memra init --no-cloud               # nur lokal, kein cloud-sync

`memra sync`

Synchronisiert dein lokales Memra mit der Cloud — danach erscheinen Projekte, Memories und Sessions live im Dashboard auf memra.ch. Voraussetzung: einmal memra login.

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

Nach dem ersten Sync läuft die Synchronisation automatisch im Hintergrund (Intervall konfigurierbar unter memra config set sync.frequency). Die „Offline"-Anzeige im Dashboard wird grün, sobald die CLI verbunden ist und gesynct hat.

`memra remember`

Speichert einen Memory-Snippet. Wird automatisch in zukünftigen Sessions des Projekts als Kontext geladen wenn 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

# Mit project-scope explizit
memra remember "..." --project memra-cli --category solution

`memra search`

Volltext-Suche über alle Memories des Projekts. Mit --global projektübergreifend.

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

`memra session`

Sessions managen — starten, pausieren, fortsetzen, archivieren.

memra session start                  # neue Session mit auto-injected context
memra session start --prompt "..."   # mit initialem Prompt
memra session list                   # alle Sessions
memra session list --archived        # archivierte einsehen
memra session resume <id>            # weiterführen — full context restored
memra session pause <id>             # explizit pausieren
memra session archive <id>           # read-only, behält Transcript

`memra worker`

Workers an Sessions andocken und Direktiven senden. Foundation der Dirigent-Pattern.

memra worker list --json                 # alle reachable Workers
memra worker attach <sid> --alias web    # bind worker
memra worker send <alias> "directive"    # directive senden
memra worker fanout a,b "directive"      # parallel dispatch (2× schneller)
memra worker send --read-only <alias> "inspect X"  # safe mode, kein write
memra worker send --force <alias> "..."  # override busy-detect
memra worker request-restart <alias>     # capacity reset
memra worker detach <alias>              # release
memra worker kv set <ns> <k> <v>          # shared blackboard
memra worker kv get <ns> <k>

`memra peer`

Lateral Messaging zwischen LIVE Claude-Code Sessions (jede mit eigenem User am Terminal). Im Gegensatz zu worker send kein Dispatch — sondern Briefing das beim nächsten User-Prompt der Ziel-Session sichtbar wird.

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`

Wiederholbare Pipelines aus Worker-Sessions. Output eines Steps fliesst zum nächsten.

memra workflow list                      # alle workflows im Projekt
memra workflow run <name>                # manueller Trigger
memra workflow run <name> --dry-run      # ohne Apply
memra workflow logs <name> --tail        # live logs
memra workflow history <name>            # letzte N runs
memra workflow create <name>             # interaktiver Builder

`memra studio`

Lokaler HTTP/SSE-Server. Dashboard (web) verbindet sich auf :9876 und streamt Audit/Health/Approvals live.

memra studio serve                       # default port 9876
memra studio serve --port 8080
memra studio serve --token <TOKEN>       # mit auth
memra studio stop                        # background-prozess killen
memra studio status                      # connected clients

Hooks

Scripts die Memra bei bestimmten Events ausführt. Definiert in .memra/hooks/<event>.sh oder konfiguriert via memra.config.json. Mit exit 1 kannst du die auslösende Operation abbrechen.

Verfügbare Events

Event	Wann	Typischer Use-Case
`PreToolUse:Bash`	Vor jedem Bash-Call	Permission-Gate, Command-Allowlist
`PostToolUse:Edit`	Nach jedem File-Edit	Auto-Format (prettier), Linter-Check
`SessionStart`	Bei Session-Begin	Custom Context-Loader, Branch-Switch
`SessionEnd`	Bei Session-Ende	Cleanup, Summary-Memory schreiben
`UserPromptSubmit`	Bei jedem User-Prompt	Prompt-Logging, PII-Scrubbing
`on_sync`	Bei Cloud-Sync	Backup zu eigener Storage
`on_error`	Bei Worker-Fehler	Sentry, Slack-Notification
`pre_session`	Bevor Session startet	Env-Setup, Dependencies
`post_session`	Nach Session-Cleanup	Audit-Log-Push

Hook-Optionen

Jeder Hook kann mit Flags konfiguriert werden:

abortOnError: Bei exit != 0 wird die Operation abgebrochen (Default: false)
background: Script wird im Hintergrund ausgeführt, blockt nichts (Default: false)
timeout: Maximale Laufzeit in Sekunden (Default: 30s)

Beispiel-Hook: Permission Gate

#!/usr/bin/env bash
# .memra/hooks/PreToolUse_Bash.sh

CMD="$1"
# Blocke destruktive Befehle
if [[ "$CMD" == *"rm -rf"* ]] || [[ "$CMD" == *"force-push"* ]]; then
  echo "Blocked: $CMD requires manual approval" >&2
  exit 1
fi
exit 0

Hooks testen

Im Dashboard unter Projects → <projekt> → Hooks findest du einen Test-Button pro Hook. Im CLI:

memra hook test PreToolUse:Bash --input "ls -la"
memra hook list                          # aktive hooks
memra hook disable PreToolUse:Bash

Workflows

Workflows verketten Worker-Sessions zu wiederholbaren Pipelines. Jeder Step ist ein eigenständiger Worker-Run — Output wird via memra worker kv oder Files an den nächsten weitergereicht.

Workflow-YAML

Workflows leben in .memra/workflows/<name>.yaml:

name: deploy-cf-pages
trigger: manual          # manual | cron | webhook | on_memory
project: memra-web

steps:
  - name: build
    worker: web-chat
    directive: "astro build, verify dist/ exists"
    timeout: 120

  - name: upload
    worker: web-chat
    directive: "wrangler pages deploy dist/"
    needs: build         # input: vorheriger output

  - name: verify
    worker: dirigent
    directive: "curl https://memra.ch — expect 200"
    needs: upload

retry:
  maxRetries: 2
  backoff: exponential   # 1s, 4s, 16s

notify:
  on_failure: you@example.com

Trigger

manual — nur via memra workflow run <name>
cron — Cron-Expression: cron: "0 9 * * 1" (jeden Montag 9 Uhr)
webhook — POST zu /webhooks/<name>
on_memory — wenn eine neue Memory mit bestimmter Kategorie geschrieben wird

Peer Briefings

Worker-Dispatch und Peer-Briefing sind zwei unterschiedliche Modi:

	Worker (Dispatch)	Peer (Briefing)
Wer empfängt	Headless Subprocess	Live Claude Session (anderer User)
Wann sichtbar	Sofort, blockt	Beim nächsten User-Prompt
Direction	Top-down (Dirigent → Worker)	Lateral (peer-to-peer)
Use case	Parallelisierung	Koordination, Info-Weitergabe

Scoping

Peer-Briefings respektieren Sandbox-Isolation — Sessions im selben Sandbox/Workflow können sich gegenseitig briefen, getrennte Workspaces nicht.

memra peer whoami                        # eigene sessionId + scope
memra peer list --scope workflow         # alle peers im aktuellen workflow
memra peer brief frontend "DB migration ready"
memra peer inbox                         # eigene received briefings

Secrets

Verschlüsselte Key-Value Speicherung pro Projekt. AES-256-GCM mit per-Project-Encryption-Keys. Secrets werden nie in Memories indexiert oder geloggt.

memra secrets add <KEY> "<value>"        # neuer Secret
memra secrets get <KEY>                  # reveal (auditlog entry)
memra secrets list                       # nur Keys, keine Values
memra secrets rotate <KEY>               # neuen Value setzen, alten 7d behalten
memra secrets delete <KEY>               # permanent

Scope-Kontrolle

Wer in der Session auf einen Secret zugreifen darf:

memra secrets scope STRIPE_KEY --all              # default
memra secrets scope STRIPE_KEY --dirigent-only    # nur Dirigent
memra secrets scope STRIPE_KEY --worker frontend  # nur dieser worker
memra secrets scope STRIPE_KEY --deny worker-3    # alle ausser dieser

HTTP API

Für Tooling-Integration bietet Memra eine lokale HTTP-API über memra studio serve (default Port 9876). Authentifiziert via Bearer-Token aus ~/.memra/auth.

Endpunkte

GET /memories — Liste aller Memories (mit ?category, ?project, ?q query)
POST /memories — Neue Memory anlegen
DELETE /memories/:id — Memory löschen
GET /sessions — Liste aller Sessions
POST /sessions — Neue Session starten
GET /workers — Worker-Status
POST /workers/:alias/dispatch — Dispatch directive
GET /search?q=... — Volltext-Suche

Beispiel

curl -H "Authorization: Bearer $(cat ~/.memra/auth)" \
     http://localhost:9876/memories

# Add memory
curl -X POST http://localhost:9876/memories \
     -H "Authorization: Bearer $(cat ~/.memra/auth)" \
     -H "Content-Type: application/json" \
     -d '{"text":"...","category":"solution","project":"memra-web"}'

Configuration

Memra-Config lebt in ~/.memra/config.json + optional per-Projekt in ./memra.config.json.

Globale Config

memra config show                    # alle Settings
memra config set sync.frequency real-time
memra config set memory.autoSave true
memra config set orchestration.budget 50
memra config set orchestration.maxWorkers 4

Projekt-Config (memra.config.json)

{
  "project": "memra-web",
  "memoryScope": "isolated",
  "secrets": ["CLOUDFLARE_API_TOKEN", "GITHUB_PAT_DEPLOY"],
  "hooks": {
    "PreToolUse:Bash": "./.memra/hooks/permission-gate.sh",
    "PostToolUse:Edit": "./.memra/hooks/format.sh"
  }
}

Analytics

Memra.ch nutzt kein Tracking-Cookie und keinen Consent-Banner. Privacy-friendly analytics (Plausible oder Umami) lassen sich optional per Env-Var aktivieren — ohne gesetzten Wert wird kein Analytics-Script geladen. Zur Aktivierung genügt es, in den Cloudflare Pages-Einstellungen PUBLIC_PLAUSIBLE_DOMAIN=memra.ch (für Plausible) oder PUBLIC_UMAMI_WEBSITE_ID + PUBLIC_UMAMI_SCRIPT_URL (für selbst gehostetes Umami) zu setzen.

Troubleshooting

`memra: command not found`

Check ob ~/.memra/bin in deinem PATH ist:

echo $PATH | tr ":" "\n" | grep memra

Falls leer, dann nach Shell-Profil hinzufügen:

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

Cloud sync failed

Check memra doctor für vollständige Diagnose:

memra doctor                         # vollständige Health-Check
memra doctor --fix                   # versucht common Issues automatisch zu fixen
memra logs --tail 50                 # letzte 50 Log-Zeilen

Worker session hängt

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

← back to landing Edit this page on GitHub →