Connecting OmniMem to Claude Code

Claude Code is Anthropic's terminal coding agent, and it's the tool I built OmniMem for in the first place. It speaks Streamable HTTP natively, so there's no bridge and no faff: point it at the URL and you're done.

OmniMem 7 serves MCP at /mcp over Streamable HTTP. The old SSE endpoint (/sse) has gone, so if you're carrying a 6.x config across, change the URL and the transport.

Quick setup

The quickest route is the CLI:

claude mcp add --transport http omnimem http://127.0.0.1:8765/mcp --scope user

Running the desktop app? Click the OmniMem icon in your tray or menu bar and pick Add to Claude Code, which runs that command for you. It reads your settings first, so it never adds OmniMem twice, and if you already have an omnimem server pointing somewhere else (a 6.x install) it offers to switch it here instead. Copy MCP URL gives you the address if you'd rather type the command yourself. Either way, restart any running Claude Code session to pick it up.

If you'd rather edit the JSON yourself, add OmniMem to ~/.claude.json:

{
  "mcpServers": {
    "omnimem": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

With an access token

If OmniMem has an access token set (MCP_AUTH_TOKEN, or Access token on the desktop app's Configuration page), send it as a header:

claude mcp add --transport http omnimem http://127.0.0.1:8765/mcp \
  --header "Authorization: Bearer your-token-here" \
  --scope user

Or in ~/.claude.json, using environment variable expansion so the token isn't sitting in a file:

{
  "mcpServers": {
    "omnimem": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp",
      "headers": {
        "Authorization": "Bearer ${OMNIMEM_TOKEN}"
      }
    }
  }
}

Global vs project config

Precedence when the same server name exists at more than one level: local, then project, then user.

Go global. The whole point of OmniMem is that what you learn in one project turns up in the next.

Auto-allow OmniMem tools

By default Claude Code asks before every OmniMem tool call, which gets old fast. Allow them all in ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__omnimem__*"
    ]
  }
}

That covers all 48 tools (remember, recall, briefing and the rest).

Auto-loaded instructions

OmniMem sends its usage guide in the MCP instructions field when Claude Code connects, so the agent already knows the session workflow, the tagging vocabulary and how to record experience. You don't have to set anything up.

If you want to tweak how Claude uses OmniMem, copy claude_config/CLAUDE.md from the repo into your project (or into ~/.claude/CLAUDE.md for every project) and edit away.

Hooks: memory that does not wait to be asked

Instructions are advice, and measurement says advice does not bind: across twenty benchmark runs with the server connected and the answer sitting in the store, the agent made zero memory calls. omnimem hook puts memory where it cannot be skipped instead, as Claude Code hooks: the project's briefing injected at session start, a tool call denied when it repeats an approach the project already abandoned, and a record written when the session ends.

One command sets them up for every project:

omnimem install-hooks

It adds the three hooks to ~/.claude/settings.json, leaves everything else in the file as it was and keeps a copy of the old one beside it. Add --project to set them up for the current project only (in ./.claude/settings.json), or --dry-run to see what it would change. Running it again changes nothing.

With the Mac app, the omnimem binary lives inside the app bundle rather than on your PATH, so run it from there:

/Applications/OmniMem.app/Contents/MacOS/omnimem install-hooks

The Flatpak can't reach Claude Code's settings from its sandbox, so add the hooks by hand there. The settings entry, and what each event will and will not do, are in the hooks guide.

Verifying the connection

Start Claude Code and run:

/mcp

You should see omnimem listed as connected. Ask Claude to call the health tool and you'll get back the record and vector counts per namespace, whether the embedding model is loaded, and the uptime.

Remote access

If OmniMem runs on another machine, point the URL at it and send the token:

{
  "mcpServers": {
    "omnimem": {
      "type": "http",
      "url": "https://omnimem.yourdomain.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

A server listening beyond localhost won't start without an access token or OAuth, so you can't forget. See remote access for reverse proxies, tunnels and OAuth.

Tips

• If tool output is being truncated, raise the limit: MAX_MCP_OUTPUT_TOKENS=50000 claude
• If the first call times out while the embedding model loads, give it longer: MCP_TIMEOUT=10000 claude (10 seconds)
• Reset project MCP approvals with claude mcp reset-project-choices

By Ric HarveyUpdated 3 November 2026All guidesThis guide on Forgejo