Connect your AI agents

Quick start

OwlMem gives every AI agent on your team one shared knowledge base and memory, over MCP. Connecting an agent takes about a minute.

Create your space. Sign in at app.owlmem.com with your email. Your first space is free.
Add OwlMem to your AI. Use this address wherever your app asks for a remote MCP server or custom connector:
```
https://mcp.owlmem.com/mcp
```
Approve it. Your app opens an OwlMem page. Pick a name for the agent and click Allow. That's it — no keys to copy.

Then tell your agents how to use it — see Teaching your agents. Every connected app shows up in the console under AI agents & tokens → Connected apps, where you can disconnect it at any time.

Claude (web, desktop and mobile)

Open Settings → Connectors and choose Add custom connector.
Name it OwlMem and paste the URL:
```
https://mcp.owlmem.com/mcp
```
Click Connect, sign in to OwlMem and click Allow.

Connectors you add on the web also work in Claude Desktop and the mobile apps. On Team and Enterprise plans an admin may need to add the connector for the organization first.

Claude Code

Add the server (use --scope user to make it available in every project):

claude mcp add --transport http --scope user owlmem https://mcp.owlmem.com/mcp

Then start Claude Code, type /mcp, select owlmem and choose Authenticate. Your browser opens the OwlMem approval page.

Codex

Adding the server starts the sign-in right away:

codex mcp add owlmem --url https://mcp.owlmem.com/mcp

If the browser step timed out, run codex mcp login owlmem. Or add it to ~/.codex/config.toml by hand and then log in:

[mcp_servers.owlmem]
url = "https://mcp.owlmem.com/mcp"

Codex asks before calling MCP tools unless you allow them in its approval settings.

ChatGPT

Open Settings → Apps & Connectors. Under Advanced settings, turn on Developer mode.
Choose Create, name it OwlMem, paste the URL and choose OAuth for authentication:
```
https://mcp.owlmem.com/mcp
```
Sign in to OwlMem and click Allow.

Availability of custom connectors depends on your ChatGPT plan and workspace settings.

Cursor

Add this to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "owlmem": { "url": "https://mcp.owlmem.com/mcp" }
  }
}

Open Cursor Settings → MCP. OwlMem shows Needs login — click it and approve in the browser.

VS Code (GitHub Copilot)

Run MCP: Add Server from the command palette, choose HTTP and paste the URL, or add it to .vscode/mcp.json:

{
  "servers": {
    "owlmem": { "type": "http", "url": "https://mcp.owlmem.com/mcp" }
  }
}

VS Code asks you to sign in the first time Copilot uses the server.

Windsurf, Gemini CLI and others

Windsurf — ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "owlmem": { "serverUrl": "https://mcp.owlmem.com/mcp" }
  }
}

Gemini CLI — ~/.gemini/settings.json, then run /mcp auth owlmem:

{
  "mcpServers": {
    "owlmem": { "httpUrl": "https://mcp.owlmem.com/mcp" }
  }
}

Any other client that supports remote MCP servers with OAuth works the same way: give it the URL and approve. OwlMem supports the MCP authorization spec (OAuth 2.1 with PKCE and dynamic client registration).

Using a token instead

Some tools can't do the sign-in flow — scripts, CI jobs, older clients. For those, create a token in the console under AI agents & tokens → Connect an AI and send it as a bearer token:

Authorization: Bearer om_…

Claude Code example:

claude mcp add --transport http owlmem https://mcp.owlmem.com/mcp --header "Authorization: Bearer $OWLMEM_TOKEN"

For a client that only runs local (stdio) servers, bridge it with mcp-remote:

{
  "mcpServers": {
    "owlmem": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.owlmem.com/mcp", "--header", "Authorization: Bearer ${OWLMEM_TOKEN}"],
      "env": { "OWLMEM_TOKEN": "om_…" }
    }
  }
}

Tokens don't expire; revoke one in the console when you no longer need it. Each token belongs to one agent name.

Tools your agents get

Knowledge is for pages people and agents read again (how-tos, decisions, project notes). Memory is for individual facts an agent can recall by meaning.

Tool	Arguments	What it does
`kb_search`	query, limit	Search the knowledge base (literal, case-insensitive). Agents should search before writing.
`kb_read`	path	Read one document.
`kb_list`	—	List every document with its description and last change. Useful for reorganising.
`kb_write`	path, content, message, mode	Create or update a document. Checks for near-duplicates and asks the agent to update the existing page instead.
`kb_move`	from, to, message	Move or rename a document, for example into `archive/`.
`kb_delete`	path, message	Delete an obsolete document. Every change is a git commit, so it can be restored.
`kb_recall`	query, limit	Recall facts from memory relevant to a question, with dates and expiry.
`kb_retain`	content, context, snapshot, valid_days, expires	Store a fact, rule or event. Changing values (prices, versions, status) should set `snapshot` or an expiry so they retire automatically.
`kb_forget`	id, reason	Retire a memory that is wrong or outdated. It can be restored in the console.

Searching and recalling are unlimited on every plan. Storing memories counts toward your plan's monthly memory writes; writing documents counts toward storage.

Teaching your agents

Agents use OwlMem much better with a few lines in their standing instructions — CLAUDE.md, AGENTS.md, Cursor rules, or a Claude project's instructions:

## Team memory (OwlMem)
- Before starting a task, use kb_search (documents) and kb_recall (facts) for the topic.
- When you learn something reusable — a fix, a gotcha, a decision — save it with kb_write
  under lessons/ or projects/<name>/. Search first and update the existing page instead of
  creating a duplicate.
- Store facts that change (prices, versions, status) with kb_retain and snapshot=true or an
  expiry, so they retire on their own.
- Never put passwords or API keys in documents or memory. Use the OwlMem vault.

New spaces start with four folders — lessons/, projects/, reference/, archive/ — each with a short README. Agents may create other folders up to three levels deep.

The vault and the owlmem command

The vault keeps credentials your agents need, end-to-end encrypted: items are encrypted on your machine with a key only you hold, and OwlMem stores ciphertext it can't read. Turn it on in the console under Vault and keep the recovery code it shows you.

Agents use it through the owlmem command (Node 18 or later):

npm install -g owlmem
owlmem login            # paste a token for this agent
owlmem vault unlock     # paste your recovery code, once per machine
owlmem run --env DB_PASSWORD=prod/db:password -- ./deploy.sh

owlmem run puts secrets into the command's environment, so the agent never sees them. To let an agent use the vault directly, add the local MCP server — decryption stays on your machine:

claude mcp add owlmem-vault -- npx -y owlmem mcp

Every read or write needs approval by a member in the console (passkey, authenticator app or GitHub), for 15 minutes to 2 hours at a time. Deleting and exporting always need a fresh approval. You can import from Bitwarden, 1Password, KeePass and .env files.

Teams, limits and your data

Members. Invite people under Team & space. Owners manage members, tokens and billing; members use everything else. Plans limit AI agents, not people.
Limits. Each plan sets the number of AI agents, storage and monthly memory writes — see pricing. When a limit is reached, writes are refused with a clear message; reading keeps working.
Your GitHub. Sync the knowledge base to a repository you own under Knowledge → Sync to your GitHub. Only Markdown files are synced.
Export and delete. Download everything or delete the space under Team & space.
Privacy. We don't train models on your data or show ads. Details in the privacy policy.

Troubleshooting

“The space has reached its AI agent limit”: Each connected agent name uses one slot. On the approval page, reuse an existing agent name, disable an agent you no longer use in the console, or upgrade.
The app says it needs to log in again: Access is refreshed automatically. If you disconnected the app in the console, or it wasn't used for 60 days, connect it again.
The sign-in email doesn't arrive: Check spam for mail from [email protected]. Links work once and expire after 15 minutes; open them in the same browser as the approval page.
“401 Unauthorized” with a token: The token was revoked or mistyped. Tokens start with om_ and are sent as Authorization: Bearer om_….

Still stuck? Email [email protected].