Companion Memory

Companion Memory is reachable three ways: an MCP server for agents, a REST API for memory operations, and a GraphQL API for search and structured queries.

One key can open MCP and REST together. GraphQL is different — scope enforcement is deny-by-default, so a key that has any scope ticked is refused everywhere no scope is declared, and GraphQL declares none. Reaching GraphQL means using a key with no scopes selected at all, which is a full-access key. See Which scopes for which job.

Find your address first

Companion Memory has no fixed port. Every example in this section writes its base URL as <memory-url> because the real value depends on how your instance runs, and guessing it is the most likely reason a correct config still fails to connect.

The .localhost suffix is Hub’s default local domain. If you set LOCAL_DOMAIN, substitute yours — see Finding Your App’s URL.

MCP endpoint

REST API

The memory endpoints live under /api/memory and require the Memory scope — which is not the same scope MCP needs. A key minted for MCP alone returns 403 here.

Scope is only half of it: these routes also declare a capability, and falling short of it is a 403 too.

curl -s -X POST "<memory-url>/api/memory/recall" \
  -H "Authorization: Bearer <memory-key>" \
  -H 'Content-Type: application/json' \
  -d '{"query":"what did I decide about the database migration"}'

$Body = @{ query = 'what did I decide about the database migration' } | ConvertTo-Json
Invoke-RestMethod -Uri '<memory-url>/api/memory/recall' -Method Post `
  -Headers @{ Authorization = 'Bearer <memory-key>' } `
  -ContentType 'application/json' -Body $Body

GraphQL API

Search and structured queries go through GraphQL rather than a REST search endpoint.

# <unscoped-key> = a key created with no scopes ticked. A scoped key is refused here.
curl -s -X POST "<memory-url>/api/graphql" \
  -H "Authorization: Bearer <unscoped-key>" \
  -H 'Content-Type: application/json' \
  -d '{"query":"query($input: SearchInput!) { search(input: $input) { __typename } }","variables":{"input":{"query":"database migration"}}}'

# <unscoped-key> = a key created with no scopes ticked. A scoped key is refused here.
$Body = @{
  query     = 'query($input: SearchInput!) { search(input: $input) { __typename } }'
  variables = @{ input = @{ query = 'database migration' } }
} | ConvertTo-Json -Depth 5
Invoke-RestMethod -Uri '<memory-url>/api/graphql' -Method Post `
  -Headers @{ Authorization = 'Bearer <unscoped-key>' } `
  -ContentType 'application/json' -Body $Body

Which scopes for which job

This trips people up because MCP and REST are genuinely separate surfaces with separate scopes. If your agent connects over MCP but every /api/memory/* call returns 403, the key is missing Memory.

A gap worth knowing about in memory_remember

The tool’s advertised input schema describes operations as an array of open-ended objects. The server actually validates each entry as a discriminated union on a kind field, which the schema does not mention:

{
  "operations": [
    {
      "kind": "entity.create",
      "entityType": "Note",
      "name": "…",
      "properties": { "body": "…" }
    }
  ],
  "dryRun": true
}

Valid kind values are entity.create, entity.update, relationship.create, and relationship.update.

An agent working only from tools/list cannot construct a valid call — it has to fail once and read the error to learn the contract. Use "dryRun": true while you work out the shape; it checks the operation’s shape and reports what would happen without writing anything.

Capability

Beyond scopes, each key carries a capability — read, write, or full — that decides what it may do on the surfaces it can reach. See Choosing a capability.

CORS

Companion Memory sends no CORS headers. Browser-based MCP clients and browser JavaScript cannot call these endpoints directly — this is a server-side and CLI integration.