memohopper (CLI)

Wire a project to memohopper memory in one command. init auto-detects the coding agents you have and wires each — doing the things that installing the MCP server alone cannot do, and which the field test showed are required for the agent to actually store/recall:

1. Registers the memohopper MCP server with each detected agent.
2. Writes a sentinel-guarded rules block into each agent's rules file (CLAUDE.md, GEMINI.md, or AGENTS.md) — the binding channel.
3. Installs a SessionStart hook where the agent supports one (Claude Code) — the deterministic per-session nudge.

npx memohopper init

Nothing you don't have installed is ever offered; at the prompt you can deselect any detected agent. Force a single agent with --host <id>, or wire every registered one with --host all.

Commands

| Command | What it does | |---|---| | memohopper init | Auto-detect present agents and wire each (register MCP + write rules + install hook where supported) | | memohopper auth | Validate a memohopper access token (PAT) | | memohopper doctor | Show what's wired and what's missing, per detected agent | | memohopper update | Refresh the rules block to the latest version | | memohopper uninstall | Reverse everything init did — unregister MCP, strip the rules block (keeping the rest of the file), remove any hook. Alias: remove |

Options

--token <pat>     access token (or env MEMOHOPPER_TOKEN)
--host <id>       force one agent instead of auto-detect, or 'all':
                  claude-code | cursor | gemini | opencode | codex | all
--workspace <id>  workspace the agent writes to       (default: auto — single, else prompt)
--mcp-url <url>   MCP endpoint   (default: https://mcp.memohopper.com/mcp)
--api <url>       API base       (default: https://api.memohopper.com)
--dry-run         print actions without writing anything
--yes             skip confirmation prompts (wires every detected agent)

Get a token from the web app → Settings → API keys, then:

npx memohopper init --token <pat>
# or
MEMOHOPPER_TOKEN=<pat> npx memohopper init

Agent support

| Agent | MCP config | Rules file | Session hook | |---|---|---|---| | Claude Code | claude mcp add → .mcp.json fallback | CLAUDE.md | ✅ SessionStart | | Gemini CLI | .gemini/settings.json (mcpServers.httpUrl) | GEMINI.md | — (none) | | OpenCode | opencode.json (mcp remote) | AGENTS.md | — (none) | | Codex CLI | ~/.codex/config.toml — machine-global | AGENTS.md | — (none) | | Cursor | 🟡 detected; automation stubbed — see Manual setup | | |

Detection is two-tier: a project marker in the working dir (e.g. .gemini/, opencode.json, .claude/) is a strong signal and is wired automatically; an agent that's only installed globally (its CLI on PATH) is offered but deselectable. Codex is global-only and always prompts, since its MCP config lives in ~/.codex/config.toml and affects every project on the machine.

The agent layer is an abstraction (src/hosts/): adding one = implement the Host interface in a single file and register it in src/hosts/index.ts.

Manual setup (unsupported hosts)

Add the MCP server (HTTP transport, Authorization: Bearer <pat>) per your host's docs, then paste the rules block from docs/portable-memory-rules.md into your host's rules file, keeping the <!-- memohopper:rules --> sentinels.

Notes

• Claude Code MCP scope: registration uses claude mcp add --scope local, which stores the token in your local, un-committed config. If the claude CLI isn't found, it falls back to writing .mcp.json (which contains the token — keep it out of version control).
• Config files contain a token: .gemini/settings.json, opencode.json, and .mcp.json embed the bearer token — keep them out of version control.
• Codex is machine-global: its [mcp_servers.memohopper] entry goes in ~/.codex/config.toml, not the project, and needs a recent Codex build with HTTP MCP support.
• Hook cwd: the SessionStart hook runs node .claude/memohopper-session-start.mjs relative to the project root (where Claude Code launches it).
• Idempotent: re-running init skips anything already present; update refreshes the rules block in place. OpenCode and Codex share AGENTS.md — wiring both is safe (the second reports the block already present).

Publishing (maintainers)

Step by step, from this cli/ directory.

1. Install + build

cd cli
npm install
npm run build          # tsc → dist/ (bin = dist/index.js, shebang preserved)

2. Smoke-test locally

node dist/index.js --help
node dist/index.js init --dry-run --host claude-code --token test   # no writes

# test the real bin resolution without publishing:
npm link            # symlinks the `memohopper` bin globally
memohopper --help
npm unlink -g memohopper

3. Check the package name

npm view memohopper        # 404 = available; otherwise pick a scoped name

If memohopper is taken, change name in package.json to a scope you own, e.g. @yourscope/memohopper. (Then the command becomes npx @yourscope/memohopper init unless you also keep the memohopper bin name — the bin key controls the invoked command, the name controls the package.)

4. Verify what will ship

npm pack --dry-run         # lists files; should be dist/** + README.md + package.json

files in package.json already limits the tarball to dist/ + README.md (source isn't published).

5. Log in and publish

npm login
npm publish                       # unscoped public package
# for a scoped package, public access must be explicit:
npm publish --access public

prepublishOnly runs npm run build automatically, so dist/ is always fresh.

6. Verify the published package

npx memohopper@latest --help

7. Releasing updates

# cli/ is not its own git repo, so skip the git tag:
npm version patch --no-git-tag-version   # use minor/major as needed
npm publish                              # 2FA: append --otp=<code>

Optional: a postinstall convenience

To let npm i -g memohopper auto-run init, you could add a postinstall script — but don't: postinstall on a global/transitive install running file-writing prompts is hostile. Keep init explicit (npx memohopper init). The whole point is that the user opts in.