Skip to content

Getting Started

Marvin runs as a single process by default — vault, hybrid index, MCP server, and CLI in one install, with no broker or background daemon.

Install

uv tool install git+https://github.com/r0k3/marvin

Try it:

marvin remember "DB" --predicate storage --value "PostgreSQL with asyncpg"
marvin search "postgres"
marvin            # dashboard: counts, recent notes, suggested next steps
marvin doctor     # what's installed, what's missing, and the fix command

The base install is retrieval-only (no LLM client). The distribution name on PyPI is marvin-memory; the CLI stays marvin.

Optional extras

# LLM sleep pass: entity extraction + two-phase consolidation
uv tool install 'marvin-memory[consolidate] @ git+https://github.com/r0k3/marvin'

# GPU embeddings + fp16 reranker (Linux + NVIDIA)
uv tool install 'marvin-memory[gpu] @ git+https://github.com/r0k3/marvin'

After installing [consolidate]:

marvin consolidate

Pending work lives in the vault as frontmatter flags (extracted / consolidated), so the pass resumes anywhere. marvin doctor reports embedder, GPU, extras, sleep endpoint, and skill state with the exact command that fixes each gap.

Claude Code plugin

For Claude Code, the plugin is the whole integration: auto-recall hooks, the 20-tool MCP server (stdio), the marvin-memory skill, slash commands (/marvin-memory:remember|recall|sleep|status|export), and a memory-curator agent.

/plugin marketplace add r0k3/marvin
/plugin install marvin-memory@marvin

Pin a global vault so every project shares memory — in ~/.claude/settings.json:

{
  "env": {
    "MARVIN_VAULT_PATH": "~/.marvin_vault"
  }
}

The plugin's hooks replace marvin hooks install --host claude. Use one or the other, not both. Details: plugins/marvin-memory.

Auto-recall hooks

By default, memory only works when the agent chooses a tool. Hooks remove that dependency: the host runs a fast marvin command at session start and on each user prompt, and stdout is injected into context.

marvin hooks install --host claude          # project (.claude/settings.json)
marvin hooks install --host claude --user   # user-level
marvin hooks install --host codex
marvin hooks install --host grok

What gets injected (budgeted; tunable via MARVIN_HOOK_SESSION_BUDGET_CHARS / MARVIN_HOOK_PROMPT_BUDGET_CHARS):

  • Session start — highest-confidence facts (current project first, via the auto project/<owner>-<repo> tag) and recent episodes. Embedder-free, ~0.4 s.
  • Each user prompt — lexical recall (FTS + entity graph; dense stream skipped) against the prompt, plus a nudge when the prompt matches a correction cue ("no, actually…", "we no longer use…") so the agent persists the fix with marvin remember ... --reason "user correction: ...".

Hooks always exit 0 — a broken vault never breaks a session. Dry-run:

marvin hook session-start
echo '{"prompt":"..."}' | marvin hook user-prompt

Host support

Host Support Mechanism Note
Claude Code full — verified end-to-end .claude/settings.json hooks plain stdout injected; env propagated
Codex CLI full (per docs; untested) .codex/hooks.json trust project hooks once via /hooks
Grok Build partial .grok/hooks/marvin.json hooks run but grok ≤0.2.118 discards their output — use skill + MCP; installed config uses hookSpecificOutput for when injection ships
OpenCode manual TypeScript plugin (experimental API) marvin hooks show --host opencode
Amp manual TypeScript plugin marvin hooks show --host amp

End-to-end check (2026-08-06, real headless sessions, unguessable fact seeded): Claude Code answered from hook-injected memory with tools disabled — including with the vault outside the project via MARVIN_VAULT_PATH. Grok Build answered via the skill path (marvin skill install --host grok → agent ran marvin search) because it drops hook stdout today.

MCP server (any client)

Stdio (default for local agents):

{
  "mcpServers": {
    "marvin": {
      "command": "marvin",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

Add "--vault-path", "~/.marvin_vault" to args if you do not set MARVIN_VAULT_PATH in the environment.

SSE / HTTP (no Docker required) for clients that connect by URL:

marvin serve --transport sse --host 127.0.0.1 --port 8421

Point the client at http://127.0.0.1:8421/sse.

Example client configs (stdio or local SSE)

Goose (~/.config/goose/config.yaml) against a local SSE server:

extensions:
  marvin:
    enabled: true
    type: sse
    name: marvin
    uri: http://127.0.0.1:8421/sse

Cursor — Settings → Features → MCP Servers → Add: type sse, URL http://127.0.0.1:8421/sse.

Claude Desktop — prefer stdio (same command/args block as above). Do not pipe SSE through curl.

The same install gives you the CLI: bare marvin is a vault dashboard; marvin search <query> is token-efficient recall; marvin --help lists every command. Full tool list: MCP tools.

Teach the agent when to remember

marvin skill install                         # Claude Code, project-level
marvin skill install --host grok
marvin skill install --user                  # user-level skills dir
marvin skill show                            # print SKILL.md for other harnesses

See The agent skill for what it teaches, multi-host paths, and marvin skill export (compile the vault into a portable skill bundle).

Safety

  • Every write is stripped of invisible Unicode (zero-width characters, bidi controls, tag block) — classic smuggling vectors a human auditor cannot see.
  • Sleep-pass LLM output is scanned for prompt-injection shapes before it may enter the vault. Notes you or your agent write directly are never content-filtered (a note about injection must remain storable).
  • Risky work can branch memory: marvin worktree start <name>, then merge or discard.

Policy detail: Architecture.

Optional: always-on cluster

The single-process default covers most deployments: sleep runs on demand (marvin consolidate) or in-process from the serve bus (marvin_trigger_sleep). For a dedicated Brain Worker across processes:

uv tool install 'marvin-memory[cluster] @ git+https://github.com/r0k3/marvin'
git clone https://github.com/r0k3/marvin.git
cd marvin
docker compose up -d
docker exec -it marvin-ollama-1 ollama pull qwen3.6:35b-a3b-q4_K_M

Set MARVIN_BUS=nats so the gateway publishes memory.created / memory.sleep to the worker. This path is optional; nothing in the base product requires Docker or NATS.