lyellr88/marm-memory/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.

1. 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.

1. 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."

1. 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.

1. 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."

1. 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.