Connect Your AI

Graphnosis exposes a local MCP server — what we call the synapse, the small background process that bridges your AI client and your cortex. You connect your AI client to it once; after that, your memory is available in every conversation — as long as the app is running and your cortex is unlocked.

The synapse takes its name from the brain: a synapse is the connection that passes a signal between neurons. In Graphnosis it’s the connection that passes a recall query into the cortex and the matched engrams back to your AI. No synapse, no memory exchange.

Why this beats dropping files into your AI client

Graphnosis pre-indexes your content into structured engram graphs (.gai files). That changes how your AI client behaves at conversation time:

• More precise answers. Your AI does not re-parse the same 200-page PDF, your meeting-notes.md archive, or your budget.xlsx from scratch every time you prompt it. The relevant slice — already chunked, tagged, and semantically indexed — is what arrives in context.
• More consistent answers across sessions. The same memory shows up the same way today, tomorrow, and three months from now. No re-uploading, no “I lost the file you shared last week,” no agentic tool fighting to re-extract the same text twice.
• Smaller context windows used. The AI receives the few hundred tokens that matter, not the tens of thousands of tokens in your raw files. Faster responses, lower token costs, more headroom for the actual conversation.
• Cross-source recall. Because everything is indexed in one graph, your AI can connect a sentence in a PDF to a related note in a markdown file to a clip you saved from a webpage — work an LLM can never do with one-shot file attachments.

This is the practical reason Graphnosis exists alongside the privacy story: AI clients become faster, more reliable, and noticeably smarter when they don’t have to re-read your files from zero every prompt.

Before you start: the app must be running

For any MCP-compatible AI client to read from your cortex, Graphnosis must be running and your cortex must be unlocked. The instructions below apply to macOS; Windows users can follow the same Claude Desktop / Claude Code / Cursor config steps — the sidecar binary and relay work on Windows.

Graphnosis state	What your AI client sees
App quit / not running	No Graphnosis tools. The AI behaves as if you don’t have a cortex.
App running, cortex locked	Graphnosis tools may appear but every recall returns “cortex is locked.”
App running, cortex unlocked	Full access to your memories. Only the chunks relevant to each prompt leave the app.

The Graphnosis main window can be closed (⌘W) — the app keeps running in your menu bar. To fully stop it, use the tray icon’s Quit option. If you want Graphnosis to start automatically at login, enable that in Settings → Auto-start.

Find your MCP socket path

When Graphnosis is running, click the menu bar icon and choose Copy MCP Config. This puts the correct JSON snippet for your MCP server path onto your clipboard.

Alternatively, the server always listens on:

~/.graphnosis/mcp.sock

(stdio transport is also supported — see below)

Claude Desktop

Open Claude Desktop’s config file:

~/Library/Application Support/Claude/claude_desktop_config.json

Add a graphnosis entry inside the mcpServers object:

{
  "mcpServers": {
    "graphnosis": {
      "command": "/Applications/Graphnosis.app/Contents/MacOS/graphnosis-sidecar",
      "args": ["--mcp-stdio"],
      "env": {
        "GRAPHNOSIS_CORTEX_PATH": "/Users/you/Documents/MyCortex"
      }
    }
  }
}

Replace /Users/you/Documents/MyCortex with the path to your cortex folder.

Restart Claude Desktop. On next launch you’ll see a small plug icon in the bottom-left of the input field — that confirms the MCP connection is live.

Windows: the config file is at %APPDATA%\Claude\claude_desktop_config.json. Use the Windows sidecar path instead: C:\Program Files\Graphnosis\graphnosis-sidecar.exe. The in-app Connect an AI client → Claude Desktop wizard generates the correct snippet for your platform automatically.

Claude Code (CLI)

Claude Code reads MCP server config from ~/.claude.json (user-level) or .mcp.json in your project root. Add a graphnosis entry to the mcpServers object:

{
  "mcpServers": {
    "graphnosis": {
      "command": "/Applications/Graphnosis.app/Contents/MacOS/graphnosis-sidecar",
      "args": ["--mcp-stdio"],
      "env": {
        "GRAPHNOSIS_CORTEX_PATH": "/Users/you/Documents/MyCortex"
      }
    }
  }
}

Reload your Claude Code session (or open a new one). Run /mcp inside Claude Code to confirm graphnosis shows as connected, then the Graphnosis tools become available in any chat.

The fastest way to wire this is the menu-bar tray’s Connect an AI client → Claude Code option — it writes the right config file for you and tells you whether to reload an active session.

Cursor

Graphnosis connects Cursor through a user-level MCP config — not a per-project file. The in-app wizard writes it for you.

Recommended setup

1. Install the optional Graphnosis Cursor plugin for rules, skills, hooks, and slash commands. The plugin does not configure MCP — it only adds instruction layers.
2. Open Graphnosis, unlock your cortex, and click the Cursor chip on the home screen (or go to Settings → AI Clients → Configure Cursor).
3. Click Apply. Graphnosis writes ~/.cursor/mcp.json with the graphnosis-mcp-relay binary and the fixed socket path ~/.graphnosis/mcp.sock. Any other MCP servers you already had are preserved.
4. Developer: Reload Window in Cursor (or reopen the app). Graphnosis tools appear in the MCP tools panel.

The relay talks to the same synapse as every other MCP client — one in-memory graph, one cortex lock, no bearer token, no GRAPHNOSIS_CORTEX_PATH env var. The socket path is cortex-independent, so one Apply survives every cortex switch.

Manual config (advanced)

If you prefer to edit by hand, the wizard produces JSON shaped like this (paths vary by platform and install location):

{
  "mcpServers": {
    "Graphnosis": {
      "command": "/Applications/Graphnosis.app/Contents/MacOS/graphnosis-mcp-relay",
      "args": ["/Users/you/.graphnosis/mcp.sock"]
    }
  }
}

On Windows, the config file is %USERPROFILE%\.cursor\mcp.json and the relay is graphnosis-mcp-relay.exe next to the sidecar in the Graphnosis install folder.

Dev builds (pnpm dev:desktop)

Sidecar rebuilds kill the synapse while Cursor keeps the relay process running. The relay reconnects automatically when you unlock. Graphnosis advertises tools.listChanged and pushes notifications/tools/list_changed after Connections → Reconnect and when the MCP tool allowlist changes, so clients that honor that notification re-fetch tools without a full IDE restart. If a client still shows Loading tools, reload the window or toggle Graphnosis in Settings → MCP.

GitHub Copilot (VS Code)

Graphnosis integrates with Copilot Chat via three paths. The in-app wizard (Settings → Configure Copilot… or the AI clients panel) shows all three options and generates your config with the bearer token pre-filled.

Option A — In-app MCP install (recommended)

Open the Graphnosis app and go to the VS Code — Copilot Chat setup (AI clients panel or Settings → Configure Copilot…). Click Install MCP Server — this opens your VS Code user MCP config file directly in VS Code so you know exactly where to paste. Copy your bearer token from the same panel, then paste the JSON snippet from Option B (pre-filled with your token) into the file.

Option B — VS Code MCP config

Create or edit the VS Code user MCP config with the snippet the wizard generates:

Platform	Path
macOS	/Users/[username]/Library/Application Support/Code/User/mcp.json
Windows	C:\Users\[username]\AppData\Roaming\Code\User\mcp.json
Linux	/home/[username]/.config/Code/User/mcp.json

{
  "servers": {
    "graphnosis": {
      "type": "http",
      "url": "http://127.0.0.1:3457/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

This registers Graphnosis as an MCP server for manual tool use. Copilot will call recall and remember when you explicitly ask it to.

The wizard’s Copy button produces the exact JSON with your token pre-filled.

Option C — GitHub Copilot CLI

For the gh copilot CLI (gh copilot suggest, gh copilot explain, etc.). This uses a different file and a different top-level key than the VS Code config above — save the snippet to ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "graphnosis": {
      "type": "http",
      "url": "http://127.0.0.1:3457/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

The app’s wizard generates this snippet with your token pre-filled — use the Copy button in the Option C panel. If you rotate your token later, update this file alongside your VS Code MCP config.

Other MCP-native clients

The same graphnosis MCP server entry works in every MCP-native client — only the config file path changes. Below is the full set we’ve verified, ranked by user base. Each is a config-file drop-in; no Graphnosis-specific work per client.

Client	Config file	Notes
Zed	~/.config/zed/settings.json (context_servers key)	Native MCP support since late 2024. Growing dev audience.
Cline (VS Code extension)	Settings panel in the Cline sidebar	Per-VS-Code-window config; nice UI for adding MCP servers.
Continue.dev	~/.continue/config.json	OSS-leaning. Same JSON shape as Claude Desktop.
Goose (Block)	~/.config/goose/profiles.yaml	Block-backed OSS MCP host. YAML, not JSON.
5ire	UI-driven MCP picker in app settings	Desktop MCP-first client. No file editing needed.
Witsy	UI-driven MCP picker in app settings	Smaller user base. Same flow as 5ire.
LibreChat / Open WebUI	Their MCP plugin pages	Self-hosted multi-model UIs. Documented in each project’s MCP docs.

The config snippet itself stays the same as the Claude Desktop / Claude Code / Cursor examples above — command, args: ["--mcp-stdio"], env: { GRAPHNOSIS_CORTEX_PATH }. Reload the client after editing.

Not yet MCP-native (need an adapter, not built yet):

• ChatGPT (Desktop / Web / Mobile) — OpenAI has committed to MCP but rollout is partial. Today, the path is a Custom GPT Action (OpenAPI 3 spec served by Graphnosis’ HTTP bridge). Tracked for a future release.
• Gemini / Bard — Google’s own function-calling format. No MCP.

Generic MCP clients (stdio transport)

Any MCP 1.x client that supports stdio transport can connect. Use:

• Command: /Applications/Graphnosis.app/Contents/MacOS/graphnosis-sidecar
• Args: ["--mcp-stdio"]
• Env: GRAPHNOSIS_CORTEX_PATH set to your cortex folder path

Connect from your phone (or any HTTP MCP client)

There are two ways to reach your cortex from another device, both configured under Settings → Mobile & Remote:

• Browser access (personal server) — Graphnosis serves the full app UI on port 3456, so you open your cortex in any phone or tablet browser. Enable it, then scan the QR (it encodes the URL + access token for one-scan unlock).
• MCP access — mobile AI clients (Claude for iOS, Claude for Android) and any tool that speaks MCP over HTTP reach your cortex on port 3457 with bearer-token auth. Copy the MCP Server URL + bearer token from the same panel and paste them into the client’s MCP server settings.

Both are opt-in and use the same Tailscale-vs-LAN security model. The full walkthrough — QR pairing, the loopback-only vs all-interfaces tradeoff, tailscale serve for HTTPS on iOS, token revocation, and running a headless personal server — is in Connect from your phone.

Why Tailscale is the recommended path: the alternative — all-interfaces on your LAN — works at home but breaks the moment you leave the house. Tailscale gives you an encrypted overlay network that follows you everywhere without exposing a port to the public internet. Install it once on both devices; the panel auto-detects the Tailscale IP.

From another computer’s AI client (Claude Code, Claude Desktop)

The stdio setups above — the graphnosis-mcp-relay in your Claude Desktop / Claude Code / Cursor config — are machine-local. The relay pipes to a Unix socket at ~/.graphnosis/mcp.sock, which only exists on the machine running Graphnosis. Tailscale routes IP traffic, not Unix sockets, so pointing a second computer’s stdio config at a remote cortex just times out with “socket never appeared.” To reach a cortex on another machine, use the HTTP MCP bridge instead.

On the server (the machine running Graphnosis): enable Settings → Mobile & Remote → MCP access (port 3457), then front it with a real HTTPS certificate over Tailscale:

tailscale serve --bg --https=8443 http://127.0.0.1:3457

tailscale serve status prints the URL — https://<your-server>.<tailnet>.ts.net:8443/mcp. This keeps the bridge on loopback (no exposed LAN port) while giving it a valid *.ts.net certificate, which Claude Desktop’s connectors require.

On the client (the second computer, on the same tailnet):

If that computer also runs Graphnosis, pointed at the remote cortex, let it do this for you. Open Settings → AI clients, pick your client, and Graphnosis writes the config itself — it asks the server where its bridge answers and which token to use, so there is nothing to copy between machines. Use this in preference to the manual steps below; the token in particular is easy to mistype and easy to confuse with the browser-access token, which is a different credential for a different port.

If the client machine reports that the server “has not published an address for its MCP bridge”, the server is behind something Graphnosis cannot detect (a reverse proxy, a tunnel). Set Settings → Mobile & Remote → MCP access → “Address for other devices” on the server to the URL clients should dial, and try again. Tailscale Serve mappings are detected automatically and need no entry.

To configure a client by hand — because Graphnosis is not installed on that machine, or you would rather see the wiring:

Step 1 — store the token once, on the client machine. Install the relay (npm i -g @graphnosis/mcp-relay) and run:

graphnosis-mcp-relay --set-credential "https://<your-server>.<tailnet>.ts.net:8443/mcp"

Paste the token from Settings → Mobile & Remote → MCP access on the server, then press Ctrl-D. It is read from standard input and written to ~/.graphnosis/remote-mcp-credentials.json with mode 0600.

Do not put the token on a command line

Earlier versions of this page told you to pass the token as --header "Authorization: Bearer …". Don’t. A command-line argument is visible to every process on the machine — anyone with a shell on it can read your token with ps aux, and no permission on the config file prevents that, because the client reads the config and then spawns a process with the value in its arguments. If you used the old shape, treat that token as exposed and rotate it under Settings → Mobile & Remote → MCP access.

The relay still accepts --header/--bearer so existing setups keep working. It warns loudly, and saves the token into the 0600 file so you can drop the flag.

Step 2 — point the client at the relay. No token appears in either config.

• Claude Code — one command:

  claude mcp add graphnosis -- graphnosis-mcp-relay "https://<your-server>.<tailnet>.ts.net:8443/mcp"

• Claude Desktop — its custom-connector flow registers from Anthropic’s cloud, which can’t reach your tailnet, so run the relay as a local stdio proxy in claude_desktop_config.json:

  {
    "mcpServers": {
      "graphnosis": {
        "command": "graphnosis-mcp-relay",
        "args": ["https://<your-server>.<tailnet>.ts.net:8443/mcp"]
      }
    }
  }

  (Use the absolute path to the relay if your MCP client doesn’t inherit your PATH.)

The relay reads the bearer from the 0600 file and sends it as an Authorization: Bearer header on your behalf — the bridge’s one-tap OAuth approval is loopback-only, so over the network that token is still the gate. It refuses to start, with a specific error, if the file is missing or if its permissions are looser than 0600. It never falls back to connecting unauthenticated.

Two operational notes: the cortex must be unlocked on the server, and a sensitive-engram recall raises its consent modal on the server’s screen (use the headless consent-phrase flow if you can’t see it).

The MCP tools

Once connected, the full Graphnosis toolset is available to your AI, organized into ten categories (Core memory, Engram discovery, Structured recall, Source operations, Engram operations, Brain maintenance, Skills (SOPs), Approximate, Conditional, and Non-deterministic). The most commonly used ones:

Tool	What it does
recall	Semantic search over your cortex. The AI calls this automatically when it needs context. Returns the top-k most relevant chunks.
dig_deeper	Escalation tool — call this when recall returns thin results (0–3 nodes) before telling the user nothing was found. Runs content recall + filename expansion + cross-engram entity hop.
remind	Same as recall but tuned for “remind me about X” intent — biases toward recently-touched memories.
remember	Store a new memory from within a conversation. Useful for saving decisions, notes, or facts mid-chat. Supports target_engram so the AI can route the note into a specific engram (with a user-confirmation banner if the name doesn’t exist or is ambiguous — see below).
edit	Propose a change to an existing memory — correction, update, or append. Returns a diff for user review; nothing is written until approved. Fires a notification when the app is in the background. (correct still works as an alias.)
apply	Commit a reviewed diff. Must be called after edit returns a diff ID.
forget	Remove a specific memory by ID.
stats	Return cortex statistics: total sources, chunks, graphs, embedding model info.
walk_skill / walk_skill_structured	Walk a Skill (a Standard Operating Procedure) step-by-step — narrative text for human-facing guidance, JSON SkillExecutionPlan for AI execution. The structured form gives the AI everything it needs to run a multi-step skill: required inputs, sub-skill calls with args + capture variables, and failure handlers.

See the full MCP Tools reference for every tool with parameter details, including the Skills (SOPs) tools (list_skills, walk_skill, walk_skill_structured, train_skill, save_skill_run, and more).

Asking the AI to save into a specific engram

When the AI calls remember with target_engram: "Book Notes", Graphnosis tries to resolve the name against your existing engrams:

• Exact name match → the note is saved immediately.
• Close matches (typos, partial words, reordered tokens — trip ↔ TripPlanning, Planning Trip ↔ TripPlanning) → a banner appears top-center in the app listing the candidates with a match-reason label. Pick the right engram or create a new one with the AI’s suggested name.
• No match → banner offers to create a new engram with that name in one click.

The AI never auto-creates engrams or silently disambiguates. Every new engram is your decision. If the app is in the background when this happens, you get a macOS notification too.

How recall works automatically

When sensitivity allows it, Graphnosis can inject context proactively — before the AI even calls recall. The sidecar listens for the conversation’s first user message, runs a fast semantic search, and prepends the top results as a system context block. This requires no AI cooperation; it works at the MCP transport layer.

If your client does not support proactive injection, the AI will use recall as a tool call in the first turn. Either way, your memory gets attached.

Add the Graphnosis docs to your cortex

A connected AI client knows whatever is in your cortex — but by default it knows nothing about Graphnosis itself. To fix that, the first time you unlock a cortex the app offers to ingest the Graphnosis documentation into a dedicated graphnosis-docs engram. Accept, and your AI can answer “how do snapshots work?” or “what does the edit tool do?” straight from recall, using the same docs you are reading now.

The documentation ships bundled inside the app — adding it is a fully offline operation with no network call. The graphnosis-docs engram lives in your cortex like any other; it just is not built from your own content.

It also stays current on its own. After an app update brings newer docs, the engram auto-refreshes to match. Two things it always respects:

• If you declined the offer, the app does not ask again or ingest anything.
• If you deleted the graphnosis-docs engram, it stays gone — the auto-refresh will not silently recreate it.

So you can have a Graphnosis-aware AI with one click, or opt out entirely — your choice either way.

Beyond AI clients: auto-ingest from your existing tools

Graphnosis is not just a memory you talk to — it’s a memory that grows on its own from tools you already use. Built-in connectors pull, receive, or watch for new content and ingest it into the engram you choose:

Connector	Ingests	Setup
RSS / Atom	new entries from any feed URL(s)	paste URLs, no credentials
GitHub	issues, PRs, releases from repos you watch	BYO Personal Access Token
Slack	starred items + (optional) channel history	BYO Slack app Bot/User Token
Trello	cards + checklists from boards you choose	BYO API Key + Token
Linear	issues with priority/state/assignee/label filters	BYO Personal API Key
Obsidian	notes from a vault folder, watched live	folder path, no credentials
GBrain	Markdown from a local knowledge repo, watched live	folder path, no credentials
AI Context Files	CLAUDE.md / AGENTS.md / .cursorrules etc. from your projects	folder paths, no credentials
Webhook	anything that can POST JSON (Zapier, IFTTT, custom scripts)	auto-generated unique URL

All connectors are configured in Settings → Connectors in the Graphnosis app. Your credentials, your apps — Graphnosis is never in the OAuth callback chain. Credentials are stored encrypted at rest in your cortex (XChaCha20-Poly1305, same as your memory files).

Full setup walkthroughs for each connector: Auto-ingest from your tools.

Troubleshooting

The MCP connection isn’t showing up in Claude Desktop

• Make sure Graphnosis is running (menu bar icon visible) and the cortex is unlocked.
• Verify the command path is correct: ls /Applications/Graphnosis.app/Contents/MacOS/graphnosis-sidecar
• Check Claude Desktop logs at ~/Library/Logs/Claude/.

recall returns no results

• Your cortex may be empty. Add some content first.
• The cortex may be locked. Click the menu bar icon and unlock it.

Hermes Agent and Hermes Desktop

Graphnosis integrates with Hermes Agent and Hermes Desktop through two co-primary paths — enable both for the best experience.

Path	What you get	Install
Memory provider	Auto-prefetch before each turn; graphnosis_recall / graphnosis_remember tools; shows on Hermes Desktop Memory screen	hermes memory setup → Graphnosis
MCP catalog	Full tool surface as mcp_graphnosis_* — edit, forget, cross_search, skills, consent	hermes mcp install graphnosis

Recommended: one-click from Graphnosis

1. Unlock your cortex in Graphnosis.
2. Open Get Connected (or Settings → AI Clients) and click Hermes.
3. Click Apply — writes both memory.provider: graphnosis and mcp_servers.graphnosis to ~/.hermes/config.yaml, plus ~/.hermes/graphnosis.json.

Start a new Hermes chat session after applying.

Manual CLI setup

hermes memory setup          # select graphnosis
hermes mcp install graphnosis
hermes graphnosis status     # after memory provider merges upstream
hermes skills install https://graphnosis.com/skills/graphnosis/SKILL.md

Manual ~/.hermes/config.yaml

memory:
  provider: graphnosis

mcp_servers:
  graphnosis:
    command: npx
    args: ["-y", "@graphnosis/mcp-relay", "${HOME}/.graphnosis/mcp.sock"]
    enabled: true
    tools:
      include: [recall, remind, remember, edit, forget, stats, cross_search, confirm_data_access]

Also create ~/.hermes/graphnosis.json:

{
  "socket_path": "/Users/you/.graphnosis/mcp.sock",
  "default_engram": "",
  "prefetch_max_tokens": 1500
}

Replace the socket path with your home directory. On Windows, use your %USERPROFILE%\.graphnosis\mcp.sock path in the args list.

Hermes tool names

When both paths are enabled, Hermes exposes two namespaces:

• Memory provider: graphnosis_recall, graphnosis_remember, graphnosis_stats
• MCP catalog: mcp_graphnosis_recall, mcp_graphnosis_edit, mcp_graphnosis_cross_search, etc.

Use MCP tools for edits and advanced operations; the memory provider handles prefetch and everyday recall/remember.

Hermes troubleshooting

Symptom	Fix
Provider not listed	Merge the Graphnosis plugin from GraphnosisApp integrations into hermes-agent, or wait for upstream release
Socket not found	Unlock Graphnosis; confirm ~/.graphnosis/mcp.sock exists
MCP tools missing	Run hermes mcp install graphnosis and restart the session
npx relay fails	Install Node 18+; or use the relay binary from Graphnosis.app

Upstream PR artifacts live in the GraphnosisApp repo under integrations/hermes-agent/ and integrations/hermes-desktop/.

---

Related

A GRAPHNOSIS.md for Your AI — the drop-in instructions file that tells your AI client to actually use Graphnosis.

MCP Tools — full reference for every tool.

Memory Across AI Clients — how the same cortex serves multiple AIs at once.

AI Access Controls — sensitivity tiers, consent gates, and the audit trail.

Connect from Your Phone — the same cortex from iOS or Android.

---

Explore by use case

→ Personal — one cortex shared across Claude, Copilot, Cursor, and any MCP client
→ Team — teammates each connect their own AI client to shared engrams via scoped tokens