Murph - Personal Health Assistant

Murph is your personal health assistant.

Install this package to get the main murph command and the full local Murph experience: onboarding, vault setup, local assistant chat, inbox capture, parser tooling, and the always-on assistant loop.

The repo implementation happens to live in packages/cli, but that is a maintainer detail. For users, @murphai/murph is the installable Murph package.

Repository · Architecture · Hosted control plane · Hosted execution

If you want a local, inspectable assistant that keeps durable truth in normal files you can read, this is the package you install.

Runtime: Node >= 24.14.1.

Supported host setup path: macOS and Linux.

Install

npm install -g @murphai/murph@latest
# or
pnpm add -g @murphai/murph@latest

Quick start

murph onboard

murph onboard installs or reuses the local parser dependencies, initializes a vault, saves that vault as the default Murph vault for later commands, and walks through assistant, channel, and optional wearable setup.

Once setup is complete, the main commands are:

murph chat
murph run
murph status
vault-cli inbox doctor

vault-cli is still available as a secondary alias for the operator surface, but murph is the primary command this package installs.

OpenClaw

If you already run OpenClaw, install the first-party Murph bundle after murph onboard:

openclaw plugins install @murphai/openclaw-plugin
openclaw gateway restart

That bundle teaches OpenClaw to call vault-cli directly against the same configured vault. It does not create a second Murph assistant runtime inside OpenClaw.

When you need to read from the vault, use this chooser:

• vault-cli show <id> for one exact canonical read id, including stable family ids such as meal_* or doc_*
• vault-cli list for structured filtering by family, kind, status, stream, tag, or date range
• vault-cli search query "<query>" for fuzzy recall or remembered phrases; --text "<query>" remains valid for explicit callers
• vault-cli timeline for chronology across journals, events, assessments, and sample summaries
• vault-cli memory show plus targeted vault-cli knowledge ... reads for saved user context
• vault-cli wearables day or wearables ... list for semantic wearable summaries
• family manifest commands for immutable import provenance

When you need route distance or duration between two points for a run, walk, ride, or hike, use:

MAPBOX_ACCESS_TOKEN=... vault-cli route estimate "123 Example St, Melbourne VIC" "St Kilda Beach" --profile walking

Add --elevation when you want an approximate elevation summary. Geometry stays omitted unless you opt in with --geometry, and walking lookups can now resolve hiking POIs such as trailheads or huts through temporary Mapbox Search Box fallback without persisting that lookup data in Murph state.

For durable local synthesis that should keep adding up inside the vault, use the derived knowledge wiki commands:

vault-cli knowledge upsert --title "Sleep notes" --body "# Sleep notes\n\nMagnesium looked helpful for sleep continuity.\n" --source-path research/2026/04/sleep-note.md
vault-cli knowledge search "sleep magnesium"
vault-cli knowledge list
vault-cli knowledge lint

What you get

• a file-native health vault with canonical writes owned by @murphai/core
• local assistant chat, runtime automation, status, outbox, canonical memory, and canonical automation commands
• a non-canonical derived knowledge wiki you can upsert and inspect under derived/knowledge/**
• inbox capture, review, backfill, and parser-driven attachment extraction
• optional local device sync through the bundled workspace-private packages/device-syncd runtime
• optional local assistant daemon support through the bundled workspace-private packages/assistantd daemon

@murphai/murph is the installable local Murph product entrypoint. The wider monorepo also contains hosted control and execution apps plus many workspace-private owner packages, but the public npm surface is intentionally small: @murphai/murph, @murphai/openclaw-plugin, @murphai/contracts, @murphai/hosted-execution, and @murphai/gateway-core.

From source

If you are developing from a checkout instead of installing the published package:

pnpm install --frozen-lockfile
pnpm onboard --vault ./vault

For package-local CLI iteration, use the source-first test lane:

pnpm --dir packages/cli test

For the explicit built-runtime and package-shape acceptance lane, use:

pnpm --dir packages/cli verify
# or the repo-composed CLI acceptance entrypoint
pnpm verify:cli

If pnpm is not available yet, use:

./scripts/setup-host.sh --vault ./vault

Config defaults

The CLI supports incur's built-in config loading for command option defaults. By default it searches ~/.config/murph/config.json.

Those incur config defaults are local CLI convenience only. Hosted execution does not snapshot or honor ~/.config/murph/config.json; portable runtime behavior must live in canonical vault state or typed operator config under ~/.murph/config.json.

• murph --config <path> ... selects an explicit config file
• murph --no-config ... disables config loading for a single run
• the published package now ships Incur's native config.schema.json so editors can validate and autocomplete those config files

Config files only supply command options, following incur's nested commands shape. For example:

{
  "commands": {
    "init": {
      "options": {
        "vault": "./vault"
      }
    }
  }
}

The shipped schema is the direct Incur output for config defaults only. Command help text, hints, examples, and agent-facing discovery stay on Incur's normal --help and --llms surfaces instead of a Murph-specific schema extension.

To refresh the shipped schema artifact from the built CLI entrypoint during package work:

pnpm --dir packages/cli gen:config-schema

Maintainer notes

The package exports the CLI runtime plus assistant helper subpaths from dist/**, exposes both murph and vault-cli bins from the same built entrypoint, and keeps src/index.ts as the package entrypoint with src/bin.ts as the launcher.

Machine-facing callers should rely on incur's native envelope via --verbose --format json instead of a Murph-specific wrapper contract.

Current repo-local package responsibilities include:

• the published command graph and install surface
• CLI-owned command routing, onboarding entry, and built binary launchers
• inbox and device command surfaces that delegate to headless owner packages
• release ownership for the public @murphai/murph package and bins

Programmatic assistant, setup, and shared usecase APIs now stay in workspace-private owner packages such as @murphai/assistant-cli, @murphai/setup-cli, @murphai/assistant-engine, and @murphai/operator-config. The public npm install story is still @murphai/murph; the release flow bundles those private owners into the CLI tarball instead of publishing them as separate npm products.

Release flow

Release and publish actions remain user-operated. The monorepo release source of truth is scripts/release-manifest.json, and the normal entrypoints are:

pnpm release:check
pnpm release:patch

Pre-release and exact-version flows use the same root script:

bash scripts/release.sh preminor --preid alpha
bash scripts/release.sh 0.1.0-rc.1 --dry-run

The release flow bumps the five public packages in the manifest to one shared version, updates packages/cli/CHANGELOG.md, writes packages/cli/release-notes/v<version>.md, and then creates a repository tag so .github/workflows/release.yml can pack and publish the public tarballs in dependency order. Workspace-private runtime packages remain in the monorepo and are bundled into the public tarballs when a public package still depends on them at runtime.

npm trusted publishing is configured per package on npm, not once per repository. Because this monorepo still publishes a small set of @murphai/* packages, maintainers should bootstrap those package-level trust bindings before relying on tag-driven release publication:

pnpm release:trust:github -- --dry-run
pnpm release:trust:github -- --yes

Those commands target the current publishable package set in scripts/release-manifest.json and bind each package to cobuildwithus/murph via .github/workflows/release.yml.

If a package is already bound to the wrong workflow or repository in npm, revoke that package's existing trust entry with npm trust list and npm trust revoke, then rerun pnpm release:trust:github -- --yes.