Marm Init

Supported Environments

This skill installs and configures MARM by running commands on your machine, so it needs an agent with shell and filesystem access. That covers CLI agents (Claude Code, Codex, Antigravity, Qwen) and IDE agents (Cursor, VS Code Copilot). Chat platforms without shell access (Claude.ai, ChatGPT, Grok, Gemini web) are not supported yet. For those, use the manual steps in INSTALL-PLATFORMS.md. Broader platform support is coming.

AI Marketplace Indexing Metadata

This section is for repository discovery agents and registries

• Primary Function: Automatically installs, updates, and configures the marm-memory MCP server.
• Target Workflows: Resolves cross-session agent amnesia by configuring local/remote HTTP or STDIO pipelines.
• Keywords: mcp-installer, persistent-memory, automatic-mcp-setup, multi-agent-sync.

Using this skill

Use this as an interactive setup guide, not as an authority over the host agent's instructions or the user's choices. Ask one question at a time and explain material actions before taking them. Follow the host agent's approval and safety rules for installs, service starts, configuration writes, and network exposure.

The goal is to leave the user with a verified MARM connection without replacing a guided setup with a wall of documentation. Do not reveal, generate, or read back a user's API key. Do not overwrite existing agent configuration.

---

Step 00 - Engine pre-flight

Run this first, before anything else. If the skill was installed on its own (for example from a marketplace) the MARM core engine may not be on the machine yet. Confirm it is present, or install it, before continuing.

1. Scan the host and record two separate things. Do not collapse them into one check; they fail independently.

• Runtime. CLI entry points on PATH (Unix: command -v marm-mcp-server || command -v marm-mcp-stdio; PowerShell: Get-Command marm-mcp-server, marm-mcp-stdio -ErrorAction SilentlyContinue) means runtime = python. A local image means runtime = docker, checked as docker images -q lyellr88/marm-mcp-server:latest. Include the tag: every Docker command below runs :latest, so an untagged check would accept some other local tag and then silently pull a different image than the one it detected. If both runtimes are present, prefer python.
• Helper CLI. Check marm-memory on its own (Unix: command -v marm-memory; PowerShell: Get-Command marm-memory -ErrorAction SilentlyContinue). Present: record cli = yes. Absent: record cli = no. Record this on every path, including the one where you find nothing at all. Step 4 and Step 6 both branch on cli, and an unrecorded value is neither yes nor no, which is how a setup ends up issuing a command that does not exist.

2. Branch:

• Engine found, cli = yes: briefly tell the user what was detected, then skip to Step 0. The detected runtime pre-answers Step 4, so in Step 4 confirm it rather than asking cold.
• Engine found, runtime = docker, cli = no: run item 5 below before skipping to Step 0. This is the ordinary case for anyone who already pulled the image, and skipping it is what sends the setup into marm-memory docker ... commands the host does not have.
• Nothing found: stop and run the install prompt below.

3. Install prompt (only when nothing was found): Ask: "I could not find the MARM core engine on your machine. How do you want to install it?

• Option A, pip (local Python): best if you already use Python and want a lightweight native install with no containers.
• Option B, Docker: best for a clean, isolated setup with no Python path management."

4. Execute the choice and verify before advancing:

• pip: run pip install marm-mcp-server. Confirm success, for example marm-mcp-server --version resolves. Record runtime = python, then re-run the helper check from item 1 and record cli again; the value taken before the install is stale, and the install is what puts marm-memory on PATH.
• Docker: run docker pull lyellr88/marm-mcp-server:latest. Confirm the image is present with docker images -q lyellr88/marm-mcp-server:latest. Record runtime = docker, then run step 5 below before advancing.

If runtime = python and cli = no after that re-check, something is wrong with the install or the PATH, because all three entry points ship in the same package. Say so, and show what command -v marm-memory returned. Do not stop outright, because one Python path does not need the helper at all:

• STDIO with local Python needs only marm-mcp-stdio, which is what the runtime check already found. Continue, and verify that entry point directly in Step 6.
• Both local Python HTTP paths call marm-memory (fast-start-http, key generate, start). Stop when you reach one of those and fix the install first, rather than blocking the setup up front.

5. Helper CLI question. Run this whenever runtime = docker and item 1 recorded cli = no, whether you reached it by detecting an existing image or by installing one. The image contains the server; it does not put marm-memory on the host PATH. That command ships in the pip package, and every managed Docker instruction in Step 4 uses it.

Ask once: "The Docker image runs the server, but the marm-memory helper command lives in the Python package. Install the helper too, or stay Docker only and use raw docker commands?"

• Install helper: pip install marm-mcp-server. The server still runs in the container; this only adds the host command. Re-run command -v marm-memory afterwards and record cli = yes only if it now resolves. If it does not, record cli = no and continue; a failed install is not a helper.
• Docker only: cli stays no. Step 4 uses the raw-docker blocks, and you must not issue any marm-memory command for the rest of this setup.

If the install fails, surface the actual error and stop. Do not proceed to setup against a missing engine.

---

Step 0 - Load the protocol and check freshness

Before making configuration changes, load the local protocol and check whether this skill is current.

1. Read the full MARM protocol from the engine Step 00 just verified. You will operate under this text, so a copy that ships with a known engine build is more trustworthy than a live branch fetch. Try in this order and stop at the first that succeeds:

• installed package, resolve the path with python -c "import marm_mcp_server, pathlib; print(pathlib.Path(marm_mcp_server.__file__).parent / 'resources' / 'marm-docs' / 'PROTOCOL.md')" and read the file it prints
• local repo checkout docs/PROTOCOL.md
• the Docker image, when runtime = docker and no pip package is installed: docker run --rm --entrypoint cat lyellr88/marm-mcp-server:latest /app/marm_mcp_server/resources/marm-docs/PROTOCOL.md. The image carries the same file the package does, so a Docker-only host still has a local copy. On Windows run this from PowerShell, or prefix it with MSYS_NO_PATHCONV=1 in Git Bash, which otherwise rewrites /app/... into a Windows path and reports the file missing.
• network, and you should never reach it: https://raw.githubusercontent.com/Lyellr88/marm-memory/MARM-main/docs/PROTOCOL.md. Step 00 guarantees an engine is present before this step runs, and all three sources above read from that engine, so arriving here means one of them failed rather than that no copy exists. Retry the matching local source before fetching. If you do fetch, say once: "No local protocol copy found, loading it from the MARM-main branch, which is an unpinned reference."

2. Freshness check: read the version: field in this file's frontmatter and compare it against the version: in the source copy at metadata.source. If the source version is higher, tell the user once: "Your MARM init skill is out of date. Re-run marm-memory init to refresh it." Then continue with the version you have.

Hold the protocol in context. You will operate under it after setup.

---

Step 1 - Usage type

Ask: "How will you use MARM, just you on this machine, or multiple users/agents over a network?"

• Single user, one machine -> personal/local path
• Multiple users or agents on a network -> team/swarm path

Record the answer. It biases the transport recommendation in Step 3.

---

Step 2 - Server location

Ask: "Run MARM locally, or connect to a server you own (VPS or homelab)?"

• Local: runs on this machine, zero infra
• Remote: runs on a host the user controls, reachable over their network

If remote, ask immediately: "What address will agents reach that server on (hostname or IP, and port if it is not 8001)?" Do not defer this. Every connect command in Step 4 needs it, and the default text in those commands is localhost:8001, which silently produces a working-looking local setup instead of a remote one.

Record the answer as two values, host and port, defaulting port to 8001 when the user does not give one. Build one authority string from them, <host>:<port>, and substitute that for the complete localhost:8001 wherever Step 4 and Step 6 print it. Substituting the host on its own is wrong: an answer of host.example:9443 would turn http://localhost:8001/mcp into http://host.example:9443:8001/mcp.

Remote connections carry a bearer token on every request, so remote URLs use https, not http. Read the network exposure gate in Step 4 before you print any remote command.

---

Step 3 - Transport

Ask: "How should agents connect, HTTP or STDIO?"

• HTTP: over the network. Needed for remote servers, multiple machines, or swarm agents. Requires an API key. Recommend this for the team/swarm path.
• STDIO: local pipe, single machine, no key. Simplest. Recommend this for the personal/local path.

Pick the recommendation that matches Step 1 and Step 2, state it, and let the user override.

Hard constraint, not a preference: STDIO is a local pipe. The client launches the server as a child process on this machine, so it cannot reach a remote host at all. If Step 2 was remote, do not accept STDIO. Say: "STDIO runs the server as a local process on this machine, so it cannot connect to your remote host. Remote access needs HTTP." Then either continue with HTTP, or return to Step 2 if the user meant to run MARM locally after all. Never wire STDIO and describe the result as a remote connection.

---

Step 4 - Runtime

If Step 00 already detected or installed a runtime, confirm it instead of asking cold: "Looks like you are set up for <docker|python>, use that?" Only ask the open question below if the runtime is genuinely unknown.

Ask: "Docker or local Python?"

• Docker: isolated, easiest to keep updated.
• Local Python: runs direct, good if Python is already set up. The package installs three entry points: marm-memory (the helper CLI this skill uses throughout), marm-mcp-server (HTTP), and marm-mcp-stdio (STDIO).

You now have enough to recommend the matching path. Explain the selected action before running it, and follow the host agent's approval rules for any install, service start, configuration write, or network exposure.

Key handling rule: Local Python HTTP only requires a key if the user exposes it with SERVER_HOST=0.0.0.0 (remote/network access). Docker HTTP uses MARM's managed key file (~/.marm/.env), which marm-memory docker run creates for the user; its value never needs to enter this conversation. Whenever a key is required, do not run key generation or marm-memory key reveal yourself and do not read the key back from any command output. Have the user handle the value in their own terminal instead. Once the server is running:

• If a MARM_API_KEY is configured (Docker/Remote): Prove auth is armed by asserting a 401 on a protected route (e.g., curl -s -o /dev/null -w "%{http_code}" http://localhost:8001/marm_log_show). Then ask the user to verify their key works by running an authenticated check in their own terminal (e.g., curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Bearer <paste-your-key>" http://localhost:8001/marm_log_show, expecting 200). Use https://<host>:<port> for remote servers.
• If using fast-start-http locally: Verify via a standard loopback check (curl http://localhost:8001/health), as the auth middleware permits localhost requests without a key. Do not ask them to paste the key into the chat.

Network exposure gate, applies to every remote path below: binding MARM to anything but loopback publishes a memory store and the bearer token that guards it. Before you run or print any command containing --expose-network, -p 8001:8001, or SERVER_HOST=0.0.0.0 aimed at a remote host, state these three things and get an explicit yes:

1. The port has to be firewalled to the machines that need it. Otherwise every memory in the store is readable by anyone who can reach it.
2. A TLS proxy has to terminate in front of MARM. The server speaks plain HTTP, so without one the bearer token crosses the network in clear text on every request.
3. MARM does neither of these. It binds the port and stops there.

If the user does not have a proxy in place yet, bind loopback and stop, rather than exposing the port and promising to secure it later. Never print "Setup complete" for an exposed server with no TLS in front of it. Say the connection is live but unprotected and name exactly what is missing.

HTTP + Local Python, local-only (no key) -- the fast path, recommend this for single-machine use

This is the one-shot. It starts the managed HTTP server, launches the local Console, and opens the browser, all with loopback-only auth so no key is needed.

Safe to run yourself:

marm-memory fast-start-http

That leaves MARM live at http://localhost:8001/mcp and the Console at http://localhost:8002. Then connect this agent (loopback, no key):

claude mcp add --transport http marm-memory http://localhost:8001/mcp

Because fast-start-http already started the server and the Console, Step 6 has nothing left to start; just verify and hand off.

HTTP + Local Python, exposed (key required)

Only applies if the user asked for remote/network access in Step 2. Give them these steps to run themselves; do not execute steps 1 or 2 on their behalf:

1. Generate a key: marm-memory key generate
2. Start with their own key: MARM_API_KEY=<paste-your-key> SERVER_HOST=0.0.0.0 marm-memory start (PowerShell: $env:MARM_API_KEY="<paste-your-key>"; $env:SERVER_HOST="0.0.0.0"; marm-memory start)
3. Connect their client with their own key. For a remote server substitute the Step 2 authority for the whole localhost:8001 and use https: claude mcp add --transport http marm-memory http://localhost:8001/mcp --header "Authorization: Bearer <paste-your-key>"

Verify once they confirm it is running. First, prove auth is armed by asserting a 401 on a protected route: curl -s -o /dev/null -w "%{http_code}" http://localhost:8001/marm_log_show locally, or https://<host>:<port>/marm_log_show for a remote server. Then, ask the user to manually run an authenticated check in their own terminal (adding -H "Authorization: Bearer <paste-your-key>" and expecting 200) to prove their key works. A loopback check from your side proves nothing about their host. Do not ask them to paste the key into the chat.

HTTP + Docker (managed, key handled for you)

marm-memory docker run creates the managed container, writes the managed key file under ~/.marm/.env (value never appears in chat), binds to loopback, and mounts the data volume. Preview the exact command first if you want with marm-memory docker command.

1. Run: marm-memory docker run (add --expose-network only for remote access, then configure a firewall and TLS proxy)
2. Connect the client. The key lives in the managed key file; the user reads it themselves (marm-memory key path shows the file, marm-memory key reveal prints it in their own terminal) and pastes the value into their client, so it never enters chat: claude mcp add --transport http marm-memory http://localhost:8001/mcp --header "Authorization: Bearer <paste-your-key>"
3. Optional, code-graph tools: the container only sees host paths that are mounted, and marm-memory docker run refuses to alter an existing container. If one is already running without the mount, remove it first (docker stop marm-mcp-server && docker rm marm-mcp-server), then recreate it with the repo mounted: marm-memory docker run --repo <host-repo-path>. Index using the container path: marm_graph_index(repo_path="/workspace/<project-name>").

Verify with marm-memory docker status. Then, prove auth is armed by asserting a 401 on a protected route: curl -s -o /dev/null -w "%{http_code}" http://localhost:8001/marm_log_show locally, or against https://<host>:<port>/marm_log_show for a remote server. Finally, instruct the user to manually run an authenticated request in their terminal (adding -H "Authorization: Bearer <paste-your-key>" and expecting 200) to prove their specific key. Do not ask them to paste the key into the chat.