MemoryAI for Claude Code

Your AI keeps forgetting you. MemoryAI gives Claude Code a real long-term memory: one that follows you across every model.

You move models. You move IDEs. Your memory stays.

Install (one command)

npx memoryai-claude install

That's it. After it finishes, restart Claude Code once and just work. Past decisions, preferences, and recent project context come back at the start of each prompt; important moments save automatically when each turn ends.

Get a key

Pick whichever is easier:

• Skip the prompt and a free key is created for you on install
• Or grab one upfront at https://memoryai.dev/connect and paste it

Health check

npx memoryai-claude doctor

Confirms the three hooks are wired and that each endpoint actually responds.

Status

npx memoryai-claude status

Tells you how many hooks are wired in user-scope and project-scope settings.

Uninstall

npx memoryai-claude uninstall

Removes the hooks from settings.json. Foreign hooks stay untouched. Memory on the server is preserved unless you delete it from the dashboard.

What gets touched

• ~/.claude/settings.json (or ./.claude/settings.json with --project)
• ~/.claude/CLAUDE.md (or ./CLAUDE.md with --project) — a short note is appended so the agent knows memory is wired.

The original file is backed up before each write.

Privacy

• API keys live in your local settings.json. They never leave your machine except to talk to the endpoint you configured.
• No telemetry from this CLI itself.
• Add MEMORYAI_NONINTERACTIVE=1 to skip prompts during scripted installs.

Troubleshooting

SessionStart hook not firing

Symptoms: No context at session start, doctor shows "session-start: absent"

Fix:

# 1. Check if hook is installed
cat ~/.claude/settings.json | grep memoryai

# 2. Check runner logs
tail -20 ~/.memoryai/runner.log

# 3. Reinstall
npx memoryai-claude uninstall
npx memoryai-claude install

Invalid credentials / 401 errors

Symptoms: doctor shows "SessionStart: failed", hooks return 401

Fix:

# Option 1: Set env vars in settings.json (recommended)
# Add to ~/.claude/settings.json under mcpServers.memoryai.env:
{
  "mcpServers": {
    "memoryai": {
      "env": {
        "HM_API_KEY": "your_key_here",
        "HM_ENDPOINT": "https://memoryai.dev"
      }
    }
  }
}

# Option 2: Reinstall with correct key
npx memoryai-claude install --key YOUR_KEY

Context not loading

Symptoms: Memory doesn't recall past sessions

Check:

1. Run npx memoryai-claude status - should show "Met X days ago"
2. Check ~/.memoryai/runner.log for bootstrap errors
3. Verify network: curl https://memoryai.dev/v1/stats
4. Try npx memoryai-claude doctor - all hooks should show "ok"

Build/install errors

Symptoms: npm install or npx fails

Fix:

# Clear cache and retry
npm cache clean --force
npx clear-npx-cache
npx memoryai-claude install

# Or install globally
npm install -g memoryai-claude
memoryai-claude install

Performance issues

Symptoms: Session start slow, high CPU usage

Check:

1. Large transcript files → normal on first compact
2. Many code anchors (100+) → 2-3s verification time expected
3. Slow network → check curl -w "@-" https://memoryai.dev/v1/stats <<< "time_total: %{time_total}"

Can't uninstall

Symptoms: Hooks remain after uninstall

Manual cleanup:

# Remove hooks from settings.json
nano ~/.claude/settings.json  # Delete hooks.SessionStart, etc.

# Remove runtime files
rm -rf ~/.memoryai/

# Remove from CLAUDE.md (if any)
nano ~/.claude/CLAUDE.md  # Remove MemoryAI notes

Still stuck?

• Check logs: ~/.memoryai/runner.log
• File an issue: https://github.com/memoryai-dev/memoryai-claude/issues
• Email: [email protected]

License

MIT.