Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Quick Start

newm1nd integration preview, unpublished: this branch combines the verified local graph/agent/Python source batch with dependency, version and tracked-UI changes. Their earlier receipts remain component history; this combined candidate needs its own checks. See integration scope.

Start with a read-only question about a real repository. You do not need to understand the full tool catalog, run missions, or configure hardware-backed authority first.

Choose the version you are using

Published 1.6.5 is available on GitHub/native, crates.io, and npm at 363bc97f2336c73e90802916804dccd2109c5746; npm latest is 1.6.5 as of 2026-10-12. This wiki also describes main; PR580’s later learning-event separation is Unreleased and absent from sealed 1.6.5.

  • Published 1.6.5: the matching wrapper/native runtime can prepare an isolated graph under an explicit workspace grant. See agent autonomy.
  • Historical 1.6.3: see the signed installation guide and historical README recipe. Its human birth and nested-runtime recipe are separate from the external-runtime 1.6.5 contract.

Install the published release

For source-preview builds, read the November dependency security update. Its unreleased lockfile changes preserve source APIs and do not replace published 1.6.5 artifacts.

Prerequisites: Node.js 18+ and a repository you can read. First follow the signed native 1.6.5 installation guide, which pins the exact artifact and verifies its signature with cosign. The 1.6.5 prebuilt assets cover Linux x86_64 and macOS x86_64/ARM64. Run this POSIX-shell walkthrough from your repository:

export M1ND_BINARY="$HOME/.local/share/m1nd/versions/1.6.5/m1nd-mcp"
"$M1ND_BINARY" --version

The npm package is a wrapper; the native m1nd-mcp runtime is separate. Require 1.6.5 at the release commit above. Pinning the wrapper alone does not pin update apply: its native target follows the registry channel. For source builds, use the contributor path with a current stable Rust toolchain and a matching wrapper/binary.

Get a first result before connecting a host

The matching 1.6.5 CLI selects an external private cache. Clear legacy runtime overrides in a subshell for this route:

(
  unset M1ND_RUNTIME_DIR M1ND_MCP_ARGS
  npx -y @maxkle1nz/m1nd@1.6.5 agent first-minute --repo . \
    --binary "$M1ND_BINARY" --query "where is configuration loaded?" --json
)

Read runtime.boot and runtime.owner_discovery: a covering served owner is reused first; otherwise first-minute prepares only the exact granted repository in an isolated cache outside the source tree. Only when reusing the automatic isolated cache does the CLI refresh the declared root before retrieval. Attached-owner freshness follows the owner’s own semantics; inspect that owner’s version, repository binding, and freshness. --binary selects the client executable, not the discovered owner’s version. Check returned source locations, gaps, and command status. A refusal is not permission to delete state, move a binding, run the human-only ceremony, or substitute generic MCP ingest.

For an explicitly located automatic cache, set M1ND_AGENT_CACHE_DIR to a private directory outside the source repository and retain --no-attach when validating an isolated binary. This cache selector is separate from M1ND_RUNTIME_DIR, which belongs to direct-runtime configuration. Cache ownership, safe ancestors and single-owner lease checks still apply.

The unreleased source CLI also accepts --no-attach --state-dir <private-directory> to select both cache and registry inside a host-authorized writable workspace, outside the indexed repository. Preview with agent scope first. This does not grant sandbox access, migrate memory or update an installed wrapper. See the storage contract for override refusals and model-cache limits.

Use the structured next command when continuing: it preserves the same state directory, isolated mode and binary, including shell quoting for paths with spaces.

In the unreleased CLI, inspect runtime.source_identity and runtime.graph_snapshot_version for branch/HEAD checks, observed refresh status and persisted-byte version. A COMPLETE code ownership receipt is not semantic completeness. Explicit/shared runtimes and attached owners do not inherit automatic-cache freshness. See automatic freshness and branch views.

The source candidate preserves owned memory during refresh by measuring the complete code-plus-memory candidate against the existing shrink guard. A refusal still requires inspection; clearing memory or lowering the guard is not a recovery recipe.

Connect your MCP host

Preview and apply the host setup:

npx -y @maxkle1nz/m1nd@1.6.5 hosts plan --host claude --project . --binary "$M1ND_BINARY"
npx -y @maxkle1nz/m1nd@1.6.5 hosts apply --host claude --project . --binary "$M1ND_BINARY" --yes

Replace claude with your host, such as codex or cursor. Some host-managed settings are printed rather than written; complete the printed steps and restart or reconnect your host. Hook support varies by host and OS. Use the host matrix for host-specific keys.

For direct stdio, keep the generated M1ND_WORKSPACE_ROOT and add an absolute M1ND_RUNTIME_DIR outside the source tree. Create that runtime before connecting, for example install -d -m 700 "$HOME/.cache/m1nd/host/repo-alpha", with a distinct location for each repository. The runtime must be a real directory owned by your user, with safe canonical ancestors and no group/other write permission. Use its actual absolute path in the host config; hosts apply does not add this selector. The first direct-stdio query can then use automatic preparation without --birth. Source files remain inputs; derived state stays in the private runtime.

For example, the environment portion of a JSON host config should contain both absolute paths (replace them with your actual paths):

{"M1ND_WORKSPACE_ROOT":"/absolute/path/to/project","M1ND_RUNTIME_DIR":"/absolute/private/runtime/repo-alpha"}

For a shared owner, attach only to an owner that already covers your repository. Preparing a new shared brain retains its separate human/authority requirements; an isolated launcher grant cannot mint one. See deployment and agent autonomy. The human-only birth ceremony remains available for the legacy/shared paths where required; agents must not perform it.

Do not copy a shared /tmp/graph.json configuration between repositories. Managed runtime state belongs to the selected runtime directory; persistence is not generally disabled just because M1ND_GRAPH_SOURCE is unset.

Ask for your first result

Ask your agent:

Use m1nd to find where configuration is loaded in this repository. Start with north, show the source locations, and list what still needs verification. Do not edit files.

The expected sequence is north → seek → source inspection. The first-query tutorial shows the wire calls. Successful setup means:

  1. The response is bound to the repository you intended.
  2. It contains useful locations that exist in that repository.
  3. The agent reports gaps and trust verdicts rather than treating retrieval as proof.

No example node count, result score, or latency is a target. Your repository determines the result.

If the first result is not useful

SymptomNext step
Native binary missingVerify the pinned installation succeeded and $M1ND_BINARY --version identifies 1.6.5 at the sealed commit; pass that path to the setup commands.
Host has no m1nd toolsComplete the printed configuration, reconnect, then inspect the host’s MCP logs.
Only a small tool menu appearsThis is intentional. help discovers the full registry; hidden tools are not necessarily removed.
needs_ingest / needs_authorityCheck the matching versions, launcher grant, private runtime, and binding. Shared-brain and legacy routes retain their authority requirements.
caller_root_mismatch / wrong_workspace_bindingStop writes and connect to the correct runtime or covering owner. Do not rebind another graph through ingest.
Writer lease already heldAttach to the existing owner rather than starting a competing writer.
seek is emptyCheck graph health, scope and node-type filters, then use the returned recovery arguments or doctor. Empty is not proof the code is absent.
reverify / abstainIn 1.6.5, all v1 calibration rows are unqualified: prediction abstains and seek stays at reverify or unprovable. Calibration cannot enable act; verify source and execution evidence.

Public ingest is not a bootstrap shortcut: default/replace and merge are policy-disabled for clients. The narrow mode: "refresh" path only re-scans an already declared exact root and can refuse unsafe root changes or graph shrinkage. It does not create a brain or add a document root.

Continue

Unreleased isolated CLI hardening: kickstart honors --no-attach --state-dir and refused results exit nonzero. Automatic caches reject conflicting attach or persistence destinations. See the freshness contract for refresh-before-query proof and its limits.

Unreleased runtime.view separates worktree/branch/commit cache identity from observed refreshed code and memory restoration. Claims stay bound to their view; restoration does not certify their freshness. Conflicting ambient Git repository selectors are refused for automatic cache selection.

For restored memory, inspect runtime.view.memory.restoration.evidence_check alongside stale counts. An inventory check or zero stale count does not certify a claim; absent/unverifiable checks remain explicit.

Unreleased agent memory-check --repo <dir> --no-attach --state-dir <dir> reviews only current-view memory without native boot or copying claims. Supplied baselines remain unauthenticated proposals; sharing is never authorized. Context capsules are discarded when a selected-anchor boundary check observes a change; unknown checks stay not proven. See the freshness contract.