Quickstart

1. Create an account

Sign up at memctl.com with GitHub. Create an organization and project in the dashboard.

2. Authenticate

npx memctl auth

This prompts for your API token (get it from Settings → API Tokens in the dashboard), verifies it, and saves it to ~/.memctl/config.json. You only do this once per machine.

3. Configure your agent

The fastest way is the init wizard:

npx memctl init

This walks you through selecting your IDE and writes the MCP config automatically.

Or use a targeted flag to skip prompts:

npx memctl init --claude    # Claude Code
npx memctl init --cursor    # Cursor
npx memctl init --windsurf  # Windsurf
npx memctl init --vscode    # VS Code + GitHub Copilot
npx memctl init --codex     # Codex
npx memctl init --roo       # Roo Code
npx memctl init --amazonq   # Amazon Q
npx memctl init --all       # All supported agents

After authenticating, your MCP config only needs the org and project - no token in project files:

{
  "mcpServers": {
    "memctl": {
      "command": "npx",
      "args": ["-y", "memctl@latest"],
      "env": {
        "MEMCTL_ORG": "your-org",
        "MEMCTL_PROJECT": "your-project"
      }
    }
  }
}

For agent-specific config locations and formats (VS Code, Cline, Zed, JetBrains, etc.), see the full agent setup guides.

4. Verify

npx memctl doctor

Or ask your agent: "Use the memory tool with action capacity to check my memory usage."

5. Start using

Your agent now has access to persistent memory. Try:

• "Store our coding conventions as a coding_style context entry"
• "What architecture decisions have been recorded for this project?"
• "Create a branch plan for the auth refactor"

Alternative: inline token

If you prefer not to run memctl auth (CI, shared environments), include the token directly:

{
  "mcpServers": {
    "memctl": {
      "command": "npx",
      "args": ["-y", "memctl@latest"],
      "env": {
        "MEMCTL_TOKEN": "your-token",
        "MEMCTL_ORG": "your-org",
        "MEMCTL_PROJECT": "your-project"
      }
    }
  }
}