Memori

Claude Code Quickstart

Add structured, persistent memory to Claude Code in three steps.

Prerequisites

  • Bun — curl -fsSL https://bun.sh/install | bash
  • Claude Code
  • Memori API key — acquire with memori signup

1. Install the Skill

Copy both SKILL.md and index.ts from integrations/claude-code into your target project's .claude/skills/memori/ directory, or into ~/.claude/skills/memori/ to make it available across all projects.

<your-project>/
└── .claude/
    └── skills/
        └── memori/
            ├── SKILL.md
            └── index.ts

2. Configure

The recommended setup is .claude/settings.local.json — Claude Code injects every entry under env into the environment of every Bash subprocess, including this skill, and Claude Code auto-gitignores the file when it creates it.

Paste the following into .claude/settings.local.json:

{
  "env": {
    "MEMORI_API_KEY": "your_memori_api_key",
    "MEMORI_ENTITY_ID": "stable_identifier_for_this_user"
  }
}

That's the full required setup. MEMORI_PROJECT_ID auto-resolves from the current Claude Code workspace, and the current Claude Code session ID is supplied to write paths automatically. Reads stay project-scoped — pass --sessionId explicitly to scope a single recall.

  • Name
    MEMORI_API_KEY
    Type
    string
    Required
    Required
    Description

    Authenticates to Memori Cloud. Available from app.memorilabs.ai.

  • Name
    MEMORI_ENTITY_ID
    Type
    string
    Required
    Required
    Description

    Stable per-user or per-agent memory namespace. Any string. If missing on first invocation, SKILL.md instructs Claude Code to pick a sensible default (slugified git config user.email, hostname, or a generated UUID) and persist it to .claude/settings.local.json. The agent only asks the user when nothing can be inferred.

  • Name
    MEMORI_PROJECT_ID
    Type
    string
    Description

    Default project scope. Auto-resolves to basename($CLAUDE_PROJECT_DIR) (the Claude Code workspace folder). Override per call with --projectId, or pin it in the env block.

  • Name
    MEMORI_SESSION_ID
    Type
    string
    Description

    Used by advanced-augmentation (write) and compaction (current-session restore). Auto-resolves to $CLAUDE_CODE_SESSION_ID (resets on /clear). Not auto-applied to recall / recall.summary, which stay project-scoped unless --sessionId is passed.

  • Name
    MEMORI_PROCESS_ID
    Type
    string
    Description

    Optional process attribution for advanced augmentation.

Alternative: shell env or .env file

If you prefer dotenv, copy .env.example to .env and place it next to index.ts (loads regardless of cwd, including global installs at ~/.claude/skills/memori/) or in the project root. Real environment variables and per-call --flag values take precedence over .env.

3. Verify

Start Claude Code. Run /skills to confirm memori is listed, then send a non-trivial message. Claude will automatically run recall before responding and advanced-augmentation after — no manual invocation needed.

Check the logs for:

[memori] command="recall" flags={...}
[memori] command="advanced-augmentation" flags={...}

CLI Reference

The skill is invoked by Claude Code automatically, but you can also run commands directly:

bun .claude/skills/memori/index.ts <command> [--flag value ...]
CommandPurpose
recallTargeted retrieval. Use with --source and --signal (see source/signal table). Project-scoped by default — pass --sessionId to narrow to a single session.
recall.summaryBroad session summary or orientation. Project-scoped by default — pass --sessionId to narrow to a single session.
advanced-augmentationRecord a user/assistant turn. Required: --userMessage, --assistantMessage. Optional: --sessionId (defaults to $CLAUDE_CODE_SESSION_ID), --trace, --summary, --model, --projectId, --processId.
compactionRestore context after Claude Code compaction. Defaults to the current workspace and session; override with --projectId / --sessionId.
feedbackSend free-form feedback. --content "..."
quotaShow remaining quota for the API key.
signupCreate a new account and acquire an API key. --email user@example.com

Flags accept both --flag value and --flag=value. On success, commands print JSON to stdout and exit 0. On failure, they print to stderr and exit 1.

Troubleshooting

  • MEMORI_API_KEY is required — credentials not in the environment. Add MEMORI_API_KEY to the env block of .claude/settings.local.json, export it in your shell, or place it in a .env file next to index.ts.
  • MEMORI_ENTITY_ID is required — namespace not configured. Add MEMORI_ENTITY_ID to the env block of .claude/settings.local.json with any stable string (e.g. slugified git config user.email, the machine hostname, or a generated UUID). On first failure, SKILL.md directs Claude Code to do this automatically when a sensible value can be inferred.
  • MEMORI_PROJECT_ID could not be resolved — neither MEMORI_PROJECT_ID nor CLAUDE_PROJECT_DIR was set. Pass --projectId, set it in the env block, or run from inside a Claude Code workspace.
  • Claude prompts on every Bash call — add Bash(bun *) and Skill(memori) to your settings.local.json.
  • Skill never fires — confirm Claude Code can see it: /skills should list memori.