Connect Your AI to SAGE

Give your AI a permanent memory in under 2 minutes. Works with any AI that supports MCP — Claude, ChatGPT, DeepSeek, Gemini, Mistral, Cursor, local models, and more.

MCP = Model Context Protocol — the standard way AI apps connect to local tools.

SAGE Running

App open or server started

Paste Config

One JSON snippet

Activate

Your AI remembers everything

Before you start: Make sure SAGE is running. If you installed the app, just open it. If you built from source, run sage-gui serve. You should see the CEREBRUM at http://localhost:8080/ui/

Open MCP settings

In Claude Desktop: Settings → Developer → Edit Config.

This opens a JSON file called claude_desktop_config.json.

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"

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.

Initialize memory

Start a new conversation and type:

Initialize your SAGE memory.

Done. Claude will initialise its memory and begin learning from every conversation — projects, preferences, and insights persist across sessions.

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.

Start a new session

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

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 file to your project containing: “Call sage_turn every turn to maintain persistent memory.” This ensures the memory lifecycle runs reliably across sessions.

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).

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.

Follow the six steps

The wizard walks through:

Verify cloudflared is installed (one-click install via Homebrew on macOS, static binary on Linux, winget on Windows).
Cloudflare login — opens your browser for OAuth, then waits for the cert file.
Pick a hostname — subdomain plus a Cloudflare zone selected from a dropdown of your active zones.
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.
Pick the agent identity the connection should run as.
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; SAGE 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.

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.

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.

Install MCP SuperAssistant

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

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

Open ChatGPT and initialize

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

You have SAGE memory tools. Use sage_turn every reply to build persistent memory.

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.

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.

Add SAGE

The config is the same everywhere — just change the SAGE_PROVIDER to match your tool:

{
  "mcpServers": {
    "sage": {
      "command": "/path/to/sage-gui",
      "args": ["mcp"],
      "env": {
        "SAGE_HOME": "~/.sage",
        "SAGE_PROVIDER": "your-tool-name"
      }
    }
  }
}

SAGE_PROVIDER keeps memories scoped per tool. Set it to something descriptive like cursor, windsurf, etc. Facts (verified truths) are shared across all providers automatically.

Restart and initialize

Restart your AI tool, then tell it:

Call sage_inception to initialize your memory. Then call sage_turn every reply.

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! That's what SAGE_PROVIDER is for. Each tool gets its own memory space. Set different provider names in each config. Facts are shared; personal observations and reflections stay scoped to each tool.

Where is my data stored?

Everything stays on your machine in ~/.sage/. The database is a single SQLite file. Nothing is ever sent to any cloud. If you enabled encryption during setup, all memories are AES-256-GCM encrypted at rest.

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

Absolutely. SAGE is model-agnostic — your memories belong to you, not to any provider. Just add the config to your new tool and your AI picks up where the last one left off. Facts are shared across providers automatically.