Connection guide

One memory.
The tools you already use.

Connect your MCP-capable AI client to SAGE. Choose your tool, add its configuration, and let your agent record useful project context for later sessions.

MCP is the protocol your AI client uses to call SAGE memory tools.
Download SAGEChoose your client ↓
SAGE Running
App open or server started
Paste Config
One JSON snippet
Activate
Record and recall useful context

Before you start: Open SAGE and complete setup. Check that CEREBRUM loads at http://localhost:8080/ui/, and keep the node running while you connect your client.

1

Open MCP settings

In Claude Desktop: Settings → Developer → Edit Config.

This opens a JSON file called claude_desktop_config.json.

2

Paste the SAGE config

Add this to the file (replace the entire contents if it's empty):

{
  "mcpServers": {
    "sage": {
      "command": "/Applications/SAGE.app/Contents/MacOS/sage-gui",
      "args": ["mcp"],
      "env": {
        "SAGE_HOME": "~/.sage",
        "SAGE_PROVIDER": "claude-desktop"
      }
    }
  }
}
Windows? Change the command to:
"command": "C:\\Program Files\\SAGE\\sage-gui.exe"
3

Restart Claude Desktop

Quit and reopen Claude Desktop. You should see a tools icon (hammer) in the chat. Click it to verify SAGE tools are listed.

4

Initialize memory

Start a new conversation and type:

Initialize your SAGE memory.
Connected. Your agent can record useful project context and recall it in later sessions. Follow the memory instructions returned by SAGE and review what it keeps in CEREBRUM.
1

Run the installer in your project

Open a terminal in your project directory and run:

# macOS (DMG install):
/Applications/SAGE.app/Contents/MacOS/sage-gui mcp install

# Built from source / Linux:
sage-gui mcp install

This creates a .mcp.json in your project, installs Claude Code hooks for reliable memory persistence, and sets up tool permissions automatically.

Tip: Run this in each project where you want SAGE memory. Each project gets its own agent identity with isolated permissions.
2

Start a new session

Close and reopen Claude Code (or start a new terminal session). SAGE tools will appear automatically.

4

Initialize memory

Tell Claude:

Initialize your SAGE memory.
Done. Claude Code will now build persistent memory across coding sessions: debugging insights, project context, preferences.
Tip: Add a CLAUDE.md instruction to call sage_inception when a new session begins and follow the memory mode it returns. Keep those instructions with your project so later sessions can find them.
ChatGPT works differently from native-MCP clients. Where Claude, Cursor, and Cline accept a JSON snippet pointing at a local sage-gui mcp binary, ChatGPT’s MCP connector requires an HTTPS-reachable endpoint and OAuth 2.0 authentication. SAGE ships built-in support for both, plus a guided setup wizard inside CEREBRUM.

Option A: OAuth Connector via the CEREBRUM Wizard (recommended)

Recommended for users with a domain on Cloudflare. The wizard handles tunnel creation, OAuth wiring, and bearer minting in six clicks. ChatGPT’s MCP connector is currently available on ChatGPT Plus, Pro, Team, and Enterprise (an OpenAI subscription requirement; SAGE itself remains free and open source).
1

Open the wizard

Launch SAGE and open the dashboard at http://localhost:8080/ui/. Go to the Network tab and find the Connect external clients section. Click Connect to ChatGPT.

2

Follow the six steps

The wizard walks through:

  1. Verify cloudflared is installed (one-click install via Homebrew on macOS, static binary on Linux, winget on Windows).
  2. Cloudflare login: opens your browser for OAuth, then waits for the cert file.
  3. Pick a hostname: subdomain plus a Cloudflare zone selected from a dropdown of your active zones.
  4. Tunnel orchestration: creates the tunnel, registers the DNS record, writes the cloudflared config (~/.cloudflared/config.yml on macOS/Linux, %USERPROFILE%\.cloudflared\config.yml on Windows) with a strict path-allowlist ingress, installs autostart (launchd on macOS, systemd on Linux; Windows users add a service in step 3 below), and verifies reachability.
  5. Pick the agent identity the connection should run as.
  6. Mint a bearer token: shown once, with one-click copy buttons for every field ChatGPT’s connector form requires.
Local-first. The wizard is pure local orchestration. No SAGE-hosted relay, no phone-home. The tunnel runs under your Cloudflare account; the SAGE project never sees the traffic.
Windows users. Step 1 uses winget install --id Cloudflare.cloudflared. If winget isn’t available (older Windows 10), grab cloudflared-windows-amd64.exe from the cloudflared releases page, rename to cloudflared.exe, drop it on your PATH (e.g. C:\Windows\System32), then re-run step 1. After the wizard finishes, the tunnel won’t auto-respawn on reboot until you register it as a Windows service; see step 3.
3

Windows only: install the autostart service

The wizard installs autostart natively on macOS (launchd) and Linux (systemd user unit), but Windows requires a one-shot manual step. Open an admin PowerShell after the wizard completes and run:

cloudflared.exe service install

This registers cloudflared as a Windows service using the config the wizard already wrote. The tunnel will now survive reboots. macOS / Linux users skip this step entirely.

4

Add the connector in ChatGPT

Open ChatGPT → Settings → Connectors → Create New → MCP Server. Paste the fields from the wizard:

  • MCP Server URL: https://<your-host>/v1/mcp/sse
  • Authentication: OAuth (auto-discovered from /.well-known/oauth-authorization-server)
  • OAuth Client ID: any string (e.g. chatgpt)
  • OAuth Client Secret: empty
  • Token endpoint auth method: none

Click Create. ChatGPT redirects to SAGE’s consent screen; pick the agent from the dropdown; the connection goes live.

Done. Bearers are revocable from the dashboard or via sage-gui mcp-token revoke <id>.
Cloudflare Bot Fight Mode. If your zone has the free-tier Bot Fight Mode enabled, it will block ChatGPT’s server-to-server OAuth callback with a Managed Challenge. Disable it for the SAGE host before connecting (Cloudflare → zone → Security → Bots).

Option B: Chrome Extension (no domain required)

For users without a Cloudflare domain or who prefer not to expose SAGE over the internet at all. Uses a Chrome extension to bridge SAGE into the ChatGPT website locally. Works regardless of ChatGPT subscription tier.
1

Install MCP SuperAssistant

Install the MCP SuperAssistant Chrome extension. It bridges MCP tools between your browser and local services.

2

Add SAGE in the extension

Open the extension sidebar and add a new MCP server:

Command: /Applications/SAGE.app/Contents/MacOS/sage-gui
Arguments: mcp
Environment:
  SAGE_HOME=~/.sage
  SAGE_PROVIDER=chatgpt
3

Open ChatGPT and initialize

Open chat.openai.com in Chrome. The extension wires SAGE in transparently. In your first message, tell ChatGPT:

Call sage_inception to initialize your memory, then follow the memory instructions it returns.
Tip: Add the same instruction under Settings → Personalisation → Custom Instructions so ChatGPT carries it across new conversations.
SAGE works with any AI that supports MCP (Model Context Protocol). This includes DeepSeek, Gemini, Mistral, Cursor, Windsurf, Cody, LM Studio, and any tool adopting the standard, cloud or local. The setup is the same pattern: point the MCP config at sage-gui mcp.
1

Find the MCP config for your AI tool

Most MCP-compatible tools have a JSON config file or settings panel for MCP servers. Check your tool's documentation for where to add MCP server configs.

2

Add SAGE

Use the SAGE MCP command below as a starting point. Your client's configuration format and the binary path depend on your tool and operating system:

{
  "mcpServers": {
    "sage": {
      "command": "/path/to/sage-gui",
      "args": ["mcp"],
      "env": {
        "SAGE_HOME": "~/.sage",
        "SAGE_PROVIDER": "your-tool-name"
      }
    }
  }
}
SAGE_PROVIDER identifies the client, such as cursor or windsurf. Use the agent identity and domain permissions configured in CEREBRUM to control which project memories it can access.
3

Restart and initialize

Restart your AI tool, then tell it:

Call sage_inception to initialize your memory, then follow the memory instructions it returns.

Troubleshooting

"SAGE tools don't appear"

Make sure SAGE is running. Check http://localhost:8080/ui/ in your browser. If the CEREBRUM loads, SAGE is running. Also verify the path to sage-gui in your config is correct.

"Connection refused"

SAGE runs on port 8080 by default. Make sure no other app is using that port, and that SAGE was started before your AI tool.

"Initialization fails"

This usually means the embedding provider isn't configured. Open the SAGE app (or run sage-gui setup) to re-run the setup wizard. Pick "Hash" for zero-setup or "Ollama" for semantic search.

Can I use SAGE with multiple AI tools at the same time?

Yes. Connect each tool with its own agent identity. Grant the agents access to the project domains you want them to share. Their current permissions determine which memories they can read and write.

Where is my data stored?

Memories are stored locally under ~/.sage/. Optional connectors, federation and remote model providers can send data to configured destinations. Vault encryption for memory contents is optional. Read the privacy details.

Can I switch from ChatGPT to Claude (or vice versa)?

Yes. Connect the new client to the same SAGE node and give its agent access to the relevant project memories. It can then recall the context you recorded, subject to its permissions and use of the memory tools.