Claude Code Installation Guide

This is the complete beginner path for memoryrouter-claude 2.0.0, which is published on npm. MemoryRouter's lifecycle hooks recall and capture project context automatically; they do not depend on the model deciding to call a tool.

Prerequisites

Have all four before installing:

1. Node.js 18 or newer. Run node --version. A result beginning with v18, v20, or a higher number is supported.
2. Claude Code installed and signed in. Start claude once and confirm it opens normally. Your normal Claude Code login is enough; MemoryRouter does not require a separate Anthropic API key.
3. A MemoryRouter account and Memory Key. In the dashboard, create or choose a vault and copy its mk_... key.
4. The project folder. Open a terminal and change into the folder you normally open with Claude Code. This determines project identity and where project-scoped settings are written.

Estimated time: 5 minutes.

Install

1. Choose the settings scope

“Project scope” here describes where Claude Code settings are installed. Automatic memories also use a stable, client-derived project handle. A project handle is an opaque ID calculated from your Git remote, Git common directory, or project folder so raw paths and repository URLs are not sent as identity metadata.

2. Run the published installer

From the project folder:

npx -y memoryrouter-claude@2.0.0 init

The installer will:

1. Ask for your Memory Key. Paste it at the prompt; input this way does not put the key in your project settings.
2. Validate the key against your vault.
3. Ask for project, local, or user settings scope.
4. Merge MemoryRouter hooks without replacing unrelated settings or hooks.
5. Save the private key in ~/.memoryrouter/config.json with owner-only permissions.

3. Read the result

A successful install prints lines similar to:

✓ valid (... memories in vault)
Hooks installed → .../.claude/settings.json
Memory scope → project (ccp_..., git-remote)
✓ Installed. Restart Claude Code or start a new session.

The exact path and memory count will be yours. The installer adds lifecycle hooks for session start, prompt recall, turn capture, failure recovery, compaction, optional subagents, and session end.

Optional install choices

Use personal/global memory instead of project memory only when you intentionally want context to cross projects:

npx -y memoryrouter-claude@2.0.0 init --global --yes

Recall global memory in addition to project memory while continuing to capture into the project:

npx -y memoryrouter-claude@2.0.0 init --include-global --yes

Global recall can surface facts from one project in another, so it is opt-in.

Authentication and permissions

Automatic hooks: Memory Key

The hooks authenticate with the private Memory Key stored under ~/.memoryrouter/. The key never goes into .claude/settings.json, .claude/settings.local.json, or your repository. A normal read-write key enables automatic recall and capture. A key ending in :read recalls but the server skips capture.

Optional MCP tools: browser OAuth

Hooks already provide automatic memory. Install MCP only if you also want explicit search_memories, store_memory, memory_status, and whole-vault deletion tools:

npx -y memoryrouter-claude@2.0.0 mcp install --local
claude mcp login memoryrouter

OAuth opens a browser. Sign in and select the same vault used by the hook key if you want both surfaces to show the same memory. A vault is the private memory collection bound to one key or OAuth connection. Run /mcp inside Claude Code to inspect the connection.

The MCP surface is additive and model-directed; the hooks remain the deterministic automatic engine. Today's remote MCP tools do not accept the hook package's project handle, so explicit MCP search/store uses the OAuth-selected vault rather than automatically enforcing the current local project partition.

Remove only MCP while keeping hooks:

npx -y memoryrouter-claude@2.0.0 mcp remove --local

Verify

1. Run doctor

npx -y memoryrouter-claude@2.0.0 doctor

A fully healthy automatic setup ends with:

✓ Automatic memory integration is healthy.

Doctor checks config migration, file permissions, the derived project handle, all three possible settings locations, hook registration, capture checkpoints, API reachability, and the optional MCP entry. MCP is optional and should not make hook verification fail.

2. Run a first store-and-recall exercise

1. Start Claude Code in the project you just configured.
2. Say: “For this installation test, the project code phrase is glacier cedar 47. Please acknowledge it.”
3. Let Claude finish the turn. Wait a few seconds so the accepted background write can complete.
4. Exit and start a new Claude Code session in the same project.
5. Ask: “What is this project's installation test code phrase?”

Success means Claude answers glacier cedar 47 from injected project memory without needing an MCP tool call. Use your own unique phrase if that example may already exist in your vault.

3. Check status

npx -y memoryrouter-claude@2.0.0 status

Status should show package version 2.0.0, a valid masked key, memory scope, a ccp_... project handle, and vault counts.

Project scope, worktrees, and expected files

Project identity is derived in this order: explicit MEMORYROUTER_PROJECT_ID, project .memoryrouter.json, user config, normalized Git remote, Git common directory, then canonical project folder. Worktrees of one Git repository therefore share an identity; unrelated projects do not. Clones on different machines share identity when their normalized Git remote matches.

Expected files after a default project install:

• ./.claude/settings.json — hook commands only; no Memory Key.
• ~/.memoryrouter/config.json — private key and integration preferences.
• ~/.memoryrouter/state/*.json — private capture cursors and retry state, pruned after 30 days by default.

Optional, non-secret project controls:

{
  "projectId": "acme-api",
  "memoryScope": "project",
  "includeGlobal": false,
  "captureSubagents": false,
  "captureEnabled": true
}

Save that as .memoryrouter.json only if you need an explicit stable project name. To disable MemoryRouter for a sensitive project without uninstalling anything, create an empty .memoryrouterignore file in that project, set "enabled": false in .memoryrouter.json, or start Claude Code with MEMORYROUTER_DISABLE=1.

Troubleshooting

Always start with:

npx -y memoryrouter-claude@2.0.0 doctor

“node” or “npx” is not recognized

Node.js is missing or not on PATH. Install Node.js 18+ from its official installer, close and reopen the terminal, and confirm node --version before retrying.

Installer says the Memory Key is invalid

Copy the key again from the MemoryRouter dashboard. Make sure no spaces or quotation marks were included. If the dashboard shows the key was rotated or revoked, use the replacement and re-run init.

Doctor finds zero hooks

You may have installed into a different scope or folder. Run doctor from the same project, then re-run init and deliberately select project, local, or user. The installer is idempotent and preserves unrelated settings.

Claude starts normally but does not recall the test phrase

• Confirm the second session started in the same project and doctor reports the same ccp_... handle.
• If the repository remote changed, re-run status and compare the handle.
• Make sure .memoryrouterignore, enabled: false, and MEMORYROUTER_DISABLE=1 are not active.
• Repeat the test after the first turn has had a few seconds to store.

Capture is pending or blocked

Doctor reports pending retry batches and malformed checkpoint files. Do not delete them first; start one normal Claude Code turn so the crash-safe capture path can retry. If the blocked count remains nonzero, contact support with doctor output—but remove paths or project names you consider sensitive.

Settings JSON is corrupt

The installer refuses to modify malformed JSON. Open the exact file named in the error, repair or move it, confirm Claude Code starts, and run init again. MemoryRouter will not overwrite the corrupt file automatically.

MCP says authentication or scope is missing

Remove and re-add the optional MCP entry, then complete browser login again:

npx -y memoryrouter-claude@2.0.0 mcp remove --local
npx -y memoryrouter-claude@2.0.0 mcp install --local
claude mcp login memoryrouter

Select the intended vault. Read-only OAuth cannot save; approve memories:write only if you want explicit MCP writes.

MemoryRouter is unreachable

Hooks fail open: Claude Code continues without injected memory and unsent capture remains available for retry. Check your network, then run doctor later. An outage should not block coding.

Upgrade

Version 2.0.0 is current. Re-run the versioned installer in each scope you use:

npx -y memoryrouter-claude@2.0.0 init

It migrates config, removes only older MemoryRouter-owned hook entries, adds the current set once, and preserves foreign hooks/settings. Run doctor after the upgrade. OAuth reconnection is not needed unless MCP permissions changed or authentication is stale.

Uninstall

Disable/remove hooks but keep private key and retry state

npx -y memoryrouter-claude@2.0.0 off

Without a scope flag, off checks local, project, and user settings and removes only MemoryRouter-owned hooks. uninstall is an alias for off.

Remove MCP too, if you installed it

Run this before or after removing hooks, using the same MCP scope you selected:

npx -y memoryrouter-claude@2.0.0 mcp remove --local

Purge local MemoryRouter credentials and checkpoints

Only after removing every hook scope that needs them:

npx -y memoryrouter-claude@2.0.0 off --purge

Purge deletes ~/.memoryrouter/, which can affect other Claude Code project installs using that same private config. Uninstall and purge do not delete memories stored in your vault. Delete individual memories in the dashboard, or review the separate whole-vault deletion safeguards.

Enterprise and admin

Teams can commit project-level .claude/settings.json so each trusted checkout receives the same hook definitions. Do not commit a Memory Key; every user or managed machine must supply its own key through private home config or MEMORYROUTER_API_KEY. Admins should:

1. Review the exact hook commands before distribution.
2. Decide whether project or user settings match the managed-device policy.
3. Supply credentials through the organization's secret-management system.
4. Run doctor as the target user on a pilot machine.
5. Use separate MemoryRouter vaults where strict client or project isolation is required.

The optional OAuth MCP connection is per user. Organization policy should grant read, write, and whole-vault delete independently; write never implies delete.

Limitations

• The ingest API returns 202 Accepted before its background durable write finishes. The client guarantees exactly-once acceptance, but a future server receipt API is needed to confirm the background durability step.
• Project identity is client-derived, and the optional remote MCP tools accept no project argument. Use a separate vault for a strict security boundary.
• Automatic capture intentionally omits raw thinking, reminders, and binary/noisy output.
• Local prompt/checkpoint state can contain sensitive text for crash recovery. Disable the integration in sensitive workspaces when that retention is inappropriate.
• Hooks are automatic; explicit MCP tool calls are still model-directed.

Support

Email hello@memoryrouter.ai. Include:

• memoryrouter-claude version and claude --version;
• your operating system and chosen settings scope;
• doctor output and the masked ccp_... project handle;
• the exact symptom and whether hooks, optional MCP, or both are affected.

Never send your Memory Key, OAuth token, full private config, or memory contents.