Murph 🌙
Murph is a conversation-first personal health assistant.
It helps people understand, decide, act, and follow through across their health. Murph can answer questions, interpret connected data, remember relevant context, help with plans and tasks, provide private or user-chosen social support, and run bounded experiments when uncertainty about what works is the real problem.
Its compounding advantage is longitudinal context: useful history, evidence, preferences, constraints, goals, actions, and outcomes that can improve later help without making the member repeat the whole story. Underneath that relationship, Murph keeps durable human-reviewed truth in Markdown, append-only machine event ledgers in JSONL, and layers a typed CLI, local daemons, and hosted control/execution surfaces on top of that vault.
The main installable product entrypoint is @murphai/murph, which gives you the murph command.
What ships here
- a file-native vault with canonical writes owned by
packages/core
- the installable
@murphai/murph package, which provides the murph CLI and onboarding flow
- provider-backed local assistant turns and automation, with runtime state under
vault/.runtime/operations/assistant/**
- a public Health Commons in
packages/health-commons for protocol pages, biomarker pages, source pages, exact revisions, and generated outcome summaries
- a two-layer knowledge system: stable health reference pages under
bank/library/** plus a non-canonical compiled personal wiki under derived/knowledge/**, synthesized by the active assistant, persisted through shared assistant/CLI write surfaces, searchable locally, and kept rebuildable
- inbox capture, assistant attachment evidence, and parser-driven audio/video transcription
- local wearable/device sync through the workspace-private
packages/device-syncd runtime bundled into @murphai/murph
- a hosted Next.js integration control plane in
apps/web
- a hosted Cloudflare execution plane in
apps/cloudflare
- public Temporal contracts and hosted-local integration; private
cobuildwithus/murph-cloud owns the worker implementation, integration CI,
and production Render deployment
- shared hosted execution contracts and env/client helpers in
@murphai/hosted-execution
- workspace-private headless owner/runtime packages such as
@murphai/assistant-engine, @murphai/operator-config, @murphai/assistant-runtime, plus the public contract package @murphai/gateway-core
Install
Runtime: Node >= 24.22.1.
Preferred install for most users:
npm install -g @murphai/murph@latest
# or
pnpm add -g @murphai/murph@latest
murph onboard
@murphai/murph is the full local Murph package. The repo keeps many internal workspace packages, but the public npm surface is intentionally narrow: @murphai/murph, @murphai/openclaw-plugin, @murphai/contracts, @murphai/hosted-execution, and @murphai/gateway-core. The remaining owner packages stay workspace-private and are bundled into those public tarballs only when a public package still needs them at runtime.
murph is the simple product entrypoint: it operates on one active vault at a time, selected during onboarding or later with murph use <path>. The lower-level vault-cli binary remains the raw explicit-vault surface for development, automation, and other contract-level consumers.
OpenClaw integration
If you already use OpenClaw, install the first-party Murph OpenClaw bundle after onboarding:
openclaw plugins install @murphai/openclaw-plugin
openclaw gateway restart
That bundle intentionally stays vault-first. It ships a Murph skill that teaches OpenClaw to use the existing vault-cli surface against your configured Murph vault through OpenClaw's built-in exec tool, rather than creating a second Murph assistant runtime inside OpenClaw.
From this repo
Supported host setup path: macOS and Linux.
Preferred setup from a checkout:
pnpm onboard --vault ./vault
pnpm onboard is the repo-local install and onboarding entrypoint. It sets up the host wrapper, installs or reuses local dependencies, builds the workspace, initializes the target vault, saves that vault as the default CLI vault, installs murph and vault-cli shims for future shells, and hands off to the interactive onboarding flow for assistant defaults, channels, and optional wearable setup.
If pnpm is not available yet, use:
./scripts/setup-host.sh --vault ./vault
pnpm onboard is the only supported repo-local onboarding command. pnpm reserves setup as a built-in command, so this repo no longer exposes a root setup script.
Direct dependency installs and review flows should prefer corepack pnpm ... so the exact pnpm version pinned in package.json#packageManager is used automatically.
After intentional dependency refreshes on a trusted machine, review blocked install scripts with corepack pnpm deps:ignored-builds and record any required approvals with corepack pnpm deps:approve-builds.
Quick start
Installed package:
murph onboard
murph use ./vault
murph model
murph assistant ask "Hello"
murph run
Use murph model any time after onboarding to reopen the assistant model/provider picker and switch the saved default model without rerunning the full setup flow.
From this repo:
pnpm onboard --vault ./vault
vault-cli vault stats
Mental model
Murph is opinionated about storage boundaries:
- Markdown is the human-facing source of truth for durable documents such as
CORE.md, journals, memory, goals, conditions, protocols, registries, and the derived personal wiki.
- JSONL ledgers are the machine-facing source of truth for append-only records such as events, samples, assessments, and audit entries.
- Blood tests remain user-facing reads over canonical
kind: "test" event-ledger records; they do not introduce a second storage family.
- Imported source artifacts are copied into
raw/** and treated as immutable.
- Derived parser output and compiled knowledge pages live under
derived/** and stay rebuildable. For the knowledge wiki specifically, derived/knowledge/index.md is the content catalog, derived/knowledge/log.md is the append-only write log, and derived/knowledge/pages/*.md are the assistant-authored personal synthesis pages.
- Local machine state lives under
.runtime/**, with durable non-canonical operational state in .runtime/operations/**, rebuildable projections in .runtime/projections/**, and ephemeral scratch state in .runtime/cache/** plus .runtime/tmp/**.
- Assistant transcripts, metadata, receipts, outbox state, and related execution residue live under
vault/.runtime/operations/assistant/**; durable user-facing memory and automation are canonical vault records.
- If a datum is user-facing, queryable, or a future product building block, it does not belong in assistant runtime first. Treat assistant runtime as execution residue, not as a staging area for product state.
The result is a system you can inspect with normal filesystem tools while still keeping write paths disciplined.
Repo structure
Only five packages are published to npm: @murphai/murph, @murphai/openclaw-plugin, @murphai/contracts, @murphai/hosted-execution, and @murphai/gateway-core. The remaining packages/* entries are workspace-private owner packages that stay installable from a checkout and can be bundled into public tarballs, but they are not intended to be consumed as standalone npm products.
| Path | Responsibility |
|---|
packages/contracts | Canonical Zod contracts, types, examples, and generated JSON Schema artifacts. |
packages/hosted-execution | Shared hosted mailbox, workspace checkpoint, runtime log/status, Temporal processing, and auth contracts for the hosted apps/web control plane and Cloudflare worker. |
packages/runtime-state | Workspace-private shared local-state taxonomy, .runtime path resolution, JSON-state versioning, and SQLite schema-version helpers. |
packages/core | Workspace-private canonical mutation owner. No other package may write canonical vault data directly. |
packages/importers | Workspace-private external adapters that normalize inputs and delegate writes to core. |
packages/inboxd | Workspace-private inbox capture, canonical evidence persistence, runtime indexing, and attachment parse-job orchestration. |
packages/parsers | Workspace-private local-first attachment parsing and derived artifact publication. |
packages/query | Workspace-private read helpers, summaries, list/search helpers, export-pack generation, and derived-knowledge parser/search/index helpers. |
packages/health-commons | Workspace-private public Health Commons owner for protocol pages, biomarker pages, sources, generated catalogs, and aggregate outcome summaries. |
packages/device-syncd | Workspace-private local wearable/device OAuth, webhook, and reconcile daemon. |
packages/assistant-engine | Workspace-private headless assistant execution/runtime owner. |
packages/operator-config | Workspace-private operator config, setup/runtime-env, and hosted assistant config owner. |
packages/assistant-cli | Workspace-private CLI-only assistant wrappers, commands, and terminal logging. |
packages/setup-cli | Workspace-private CLI-only onboarding, host setup, and setup-wizard package. |
packages/gateway-core | Headless transport-neutral gateway boundary. |
|
Local and hosted surfaces
Murph now has three distinct runtime tiers:
1. Local operator surface
vault-cli / murph for vault operations, assistant turns, automation, onboarding, and diagnostics- the workspace-private
packages/device-syncd runtime for local wearable sync
2. Hosted control plane
apps/web owns hosted onboarding, billing, OAuth callbacks, webhook intake, device-sync control-plane metadata, sparse routing state, encrypted hosted mailbox rows, workspace checkpoint metadata, and hosted runtime status/logs- it does not own canonical health data
- webhook and app paths append durable mailbox facts and signal Temporal only; they do not directly nudge a user runner in Cloudflare
3. Hosted execution plane
apps/cloudflare restores encrypted hosted bundles, coordinates per-user runtime passes, keeps only DO-local runner coordination state, and invokes the workspace-private @murphai/assistant-runtime package against web-owned mailbox/checkpoint/log ports- private
cobuildwithus/murph-cloud runs the per-user Temporal workflow worker that reads web-owned reconciliation facts, calls Cloudflare ensure-processing, and stores only pointer-level orchestration state
- Cloudflare returns
runtime_processing_accepted or retry_later and owns start, wake, active-fence alarm cleanup, and execution cleanup for the active runner through ensure-processing
- the hosted execution plane is intentionally separate from the public hosted web app
CLI surface
The root CLI is no longer just a vault editor. The built command surface includes:
- health-vault operations such as
init, show, list, timeline, journal, document, meal, samples, audit, vault, and the health registry commands
assistant for local chat, status, outbox, cron, automation, and provider-backed runtime controldevice for local wearable/device auth, status, and daemon control- env-gated route estimation through
vault-cli route estimate, which uses temporary Mapbox geocoding and Search Box lookups for distance, duration, hiking POIs, and optional approximate elevation between two points without persisting the route payload in Murph state
- root shortcuts such as
chat, run, status, doctor, and stop
- AI-assisted synthesis helpers such as
knowledge
The knowledge surface is intentionally narrow: use it to persist pages, inspect saved pages, lint the wiki, rebuild the index, and tail the append-only wiki log. The assistant's wiki-maintainer workflow itself lives in the runtime prompt plus the dedicated assistant.knowledge.* tools, not in repo AGENTS.md.
For operator UX, prefer murph. It resolves one active vault and no longer expects ad hoc --vault switching on normal commands. Use murph use <path> to select a different existing vault, or murph onboard --vault <path> to create/select one during setup. Use vault-cli when you intentionally need the raw explicit-vault contract.
Choosing a read command
- Use
vault-cli show <id> when you already know one exact query-layer record id to inspect.
- Use
vault-cli list when you need structured filtering by family, kind, status, stream, tag, or date range.
- Use
vault-cli search query --text "..." when the target is fuzzy, remembered by phrase, or buried across notes and record bodies.
- Use
vault-cli timeline when the question is chronological: what changed, what happened over a window, or what stood out over time.
- Use
vault-cli memory show, targeted vault-cli knowledge ... reads, and the relevant preferences surface when you need the user's saved current-state context.
- Use
vault-cli wearables day or the wearables ... list commands for semantic wearable summaries before drilling into raw events or samples.
- Use family
manifest commands such as meal manifest, document manifest, intake manifest, and workout manifest when you need immutable import provenance or raw-source context.
Quick help:
pnpm vault-cli --help
Common workflows
Operator flows
pnpm onboard --vault ./vault
murph use ./vault
murph assistant ask "Summarize my recent activity"
murph run
murph device daemon start
Developer flows
pnpm dev
pnpm typecheck
pnpm test
pnpm verify:acceptance
pnpm --dir apps/cloudflare verify
pnpm dev is the repo-root local hosted lane. It pulls the linked Vercel development env for apps/web, runs hosted-web Prisma generate plus local schema sync, and starts both apps/web and the local Cloudflare worker together. One-time local prerequisites:
- either
cd apps/web && vercel link or run vercel link --repo from the repo root
- log into Vercel CLI and enable project OIDC for the linked web project
- optional: copy
apps/cloudflare/.dev.vars.example to apps/cloudflare/.dev.vars when you want to pin local Worker secrets or add provider-specific Worker vars; otherwise pnpm dev uses Wrangler's documented local process-env path for required Worker secrets and CLI --var overrides for local non-secret vars
- run local Postgres on
127.0.0.1:5432; by default pnpm dev ignores a pulled Vercel DATABASE_URL and uses the murph_device_sync database there
- treat
127.0.0.1:5432/murph_device_sync as the canonical local hosted debugging database for local Docker runs, including hosted runtime logs and AI usage rows
- install or check the Temporal CLI with
pnpm temporal:cli:setup or pnpm temporal:cli:check; pnpm dev and hosted-local E2E manage the local Temporal dev server and worker automatically. The managed dev server exposes the Temporal Web UI at http://127.0.0.1:8233 by default, or at MURPH_DEV_TEMPORAL_PORT + 1000 when the Temporal frontend port is overridden. Hosted-local E2E defaults to headless Temporal because those tests do not use the dashboard; for interactive pnpm dev, set TEMPORAL_DEV_HEADLESS=1 only when you intentionally want no dashboard.
- optional: set
MURPH_DEV_DATABASE_URL or shell DATABASE_URL for a different local database; set MURPH_DEV_USE_VERCEL_DATABASE_URL=1 only when you intentionally want the pulled Vercel development database
- keep the linked Vercel development env populated with the real hosted signup secrets you need locally, such as Privy credentials
- optional: put local-only Stripe test checkout values in
.tmp/.env.hosted-local-stripe; root pnpm dev loads that file after the Vercel env pull and before shell env overrides, so local sk_test_... and price_... values can override shared Development env without being committed
- optional: install the Stripe CLI (
brew install stripe/stripe-cli/stripe) and run stripe login once. pnpm dev then auto-launches stripe listen for hosted onboarding webhooks and captures the per-developer signing secret from the listener's startup output into the web child's env. Set to opt out; see for the full contract.
Repeatable launcher sanity check:
NEXT_DIST_DIR_MODE=smoke MURPH_DEV_WEB_PORT=3013 MURPH_DEV_WORKER_PORT=8793 pnpm dev
That variant keeps the check off the default apps/web/.next-dev lock and default localhost ports while still exercising the same root launcher, Vercel env pull, Prisma setup, and Wrangler/Containers startup path.
Startup readiness also POSTs the internal deploy-smoke route with HOSTED_EXECUTION_SMOKE_RUNNER_CONTAINER=true, so pnpm dev proves the local Worker can boot the runner container and observe the prepared runner bundle before printing ready. Set MURPH_DEV_SKIP_RUNNER_SMOKE=1 for a focused Worker-only debugging loop.
For secondary worktrees, do not rely on ports alone. Use the hosted-local
worktree helper so the database, generated local crypto state, Wrangler state,
Next dist dir, optional MinIO data, and webhook tunnel target are isolated
together:
pnpm hosted-local worktree doctor <slug>
pnpm dev:worktree <slug>
pnpm hosted-local worktree down <slug>
See agent-docs/operations/hosted-local-worktree-dev.md for the full contract
and manual fallback.
The repo verification baseline for docs/process-only and ordinary repo work remains:
pnpm typecheck
pnpm test
pnpm verify:acceptance
Development notes
Optional: local HTTPS dev (passkey, Telegram bot domain)
Some flows need a real hostname over HTTPS — WebAuthn refuses 127.0.0.1, and Telegram's /setdomain refuses localhost. The repo ships a Caddyfile that terminates TLS for local.withmurph.ai:3443 and forwards to the regular dev server on http://127.0.0.1:3000. pnpm dev auto-spawns it when both caddy is on PATH and the Caddyfile exists; otherwise it's skipped silently.
One-time setup:
echo "127.0.0.1 local.withmurph.ai" | sudo tee -a /etc/hosts
brew install caddy nss
sudo caddy trust
Then pnpm dev runs as usual and the browser-facing URL becomes https://local.withmurph.ai:3443. Add that origin to the Privy dashboard allowlist and set the Telegram bot's /setdomain to local.withmurph.ai (Telegram ignores the port). Internal harness callers keep using http://127.0.0.1:3000. Set MURPH_DEV_SKIP_TLS_PROXY=1 to opt out.
License
Murph is licensed under Apache-2.0. The published @murphai/* packages now carry Apache 2.0 metadata and include a copy of the license text in their package contents. See LICENSE for the full terms.
Read next
