Shared memory and context tools for agentic work.
Code Rooms
# 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](../../../RELEASE-2.0.0-PROPOSAL.md).
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](https://github.com/maxkle1nz/m1nd/releases/tag/v1.6.5), 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](https://github.com/maxkle1nz/m1nd/blob/v1.6.5/docs/AGENT-AUTONOMY.md).
- **Historical 1.6.3:** see the [signed installation guide](https://github.com/maxkle1nz/m1nd/blob/main/docs/INSTALL-1.6.5.md) and [historical README recipe](https://github.com/maxkle1nz/m1nd/blob/main/README.md#historical-pinned-163-install-prepare-connect). 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](https://github.com/maxkle1nz/m1nd/blob/main/CHANGELOG.md#security). 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](https://github.com/maxkle1nz/m1nd/blob/main/docs/INSTALL-1.6.5.md), 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:
```bash
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](contributor-devkit.md) 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](https://github.com/maxkle1nz/m1nd/blob/main/docs/AGENT-AUTONOMY.md#explicit-storage-in-an-already-writable-workspace-unreleased-cli) 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](https://github.com/maxkle1nz/m1nd/blob/main/docs/AUTOMATIC-GRAPH-FRESHNESS.md).
The source candidate [preserves owned memory during refresh](https://github.com/maxkle1nz/m1nd/blob/main/docs/REFRESH-OWNED-MEMORY.md) 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](https://github.com/maxkle1nz/m1nd/blob/main/docs/HOST-INTEGRATION-MATRIX.md) 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):
```json
{"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](https://github.com/maxkle1nz/m1nd/blob/main/docs/deployment.md) and [agent autonomy](https://github.com/maxkle1nz/m1nd/blob/v1.6.5/docs/AGENT-AUTONOMY.md). 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](first-query.md) 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
| Symptom | Next step |
|---|---|
| Native binary missing | Verify 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 tools | Complete the printed configuration, reconnect, then inspect the host's MCP logs. |
| Only a small tool menu appears | This is intentional. `help` discovers the full registry; hidden tools are not necessarily removed. |
| `needs_ingest` / `needs_authority` | Check the matching versions, launcher grant, private runtime, and binding. Shared-brain and legacy routes retain their authority requirements. |
| `caller_root_mismatch` / `wrong_workspace_binding` | Stop writes and connect to the correct runtime or covering owner. Do not rebind another graph through `ingest`. |
| Writer lease already held | Attach to the existing owner rather than starting a competing writer. |
| `seek` is empty | Check graph health, scope and node-type filters, then use the returned recovery arguments or `doctor`. Empty is not proof the code is absent. |
| `reverify` / `abstain` | In 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
- [First query](first-query.md): orient, find code, verify, remember
- [Multi-agent workflows](multi-agent.md): share a local owner and coordinate
- [Deployment](https://github.com/maxkle1nz/m1nd/blob/main/docs/deployment.md): persistent owners and transport limits
- [Contributor development kit](contributor-devkit.md): source builds and private development state
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](../../../AUTOMATIC-GRAPH-FRESHNESS.md)
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](../../../AUTOMATIC-GRAPH-FRESHNESS.md).