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

Read the address off the Companion Memory app page. 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. In the Hub dashboard, open the Companion Memory app and read the Access points card. It lists up to three routes, each with a copy button: Local access, Private VPN, and Public domain. A route that is not set up shows Not configured or Unavailable.

<host-port> is the port Hub published for the app. Hub tries the app’s own port, 8642, first, so on a typical install it is 8642. If 8642 is already taken when you install, or you chose a different port in the install form, Hub picks a free port in the 10000–60000 range instead, and the number differs per appliance. Do not assume 8642 — the Local access value is authoritative.

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

The same table as a picture — each surface opens only to the scope it declares, and the unscoped key is the only one that reaches the surfaces that declare none:

flowchart LR
    K["Your Companion<br/>Memory key"] --> S{"Scopes ticked"}
    S -->|"MCP + Intents"| M["MCP server<br/>/api/mcp — tools"]
    S -->|"Memory"| R["REST — /api/memory/*<br/>recall, context, write,<br/>turn, compact"]
    S -->|"Capture"| C["Bulk ingest<br/>/api/v1/* write routes,<br/>/api/files upload"]
    S -->|"none — full access"| G["GraphQL and graph routes<br/>/api/graphql"]

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.

Capture is the write-only lane for agents that stream observations in and read nothing back — Companion Capture and the browser extension. It opens the /api/v1/* bulk-ingest endpoints (events, communications, contents, things, browser-activity, notes, positions, receipts, product-models, observations, plus inventory, a deprecated alias of things), POST /api/files/upload, and PATCH /api/files/:id. It deliberately opens nothing else — no /api/memory/*, no GraphQL.

What an MCP client sees

A key with MCP and Intents sees Companion Memory’s curated intents, which the server advertises as tools. Each intent’s dotted id becomes a tool name with _ in place of the dot, so memory.recall appears as memory_recall. As of v2026.10.2 there are 36:

Capability filters that list: a read key sees 26 of the 36, a write key sees 32, and a full key sees all 36. memory_forget, messaging_send, planning_completeTask, and import_import_inbox are the four a write key does not get. Even a full key sees those four held for your approval by default — see A full key still waits for Approvals. The server also publishes the catalog itself as the intents://catalog resource. A key with no scopes selected additionally sees a query_* or mutation_* tool for every GraphQL field — 112 queries and 138 mutations as of v2026.10.2.

The operation shape in memory_remember

Every entry in operations is a discriminated union on a kind field. This is now advertised: the tool’s input schema marks kind required and enumerates the four values, and the description repeats them — so an agent working from tools/list alone can construct a valid call. (Earlier releases published operations as an array of open-ended objects, which is why some clients still guess.)

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

entityType is free text as far as the database is concerned (any ^[A-Z][A-Za-z]*$ value inserts), but only the graph’s own vocabulary is browsable afterwards. Stick to Person, Place, Concept, Item, Event, Content, Communication, File, Group, Pet, Product or Tag — an invented type still draws on the Graph view, as a neutral node with the default color and its own legend entry (no type filter can exclude it either), but it is a dead end from there: no explorer type filter maps to it, clicking it resolves to no record so the drawer falls back to the graph’s own name/type card, and the List, Gallery and Map views cannot browse it.

Valid kind values are entity.create, entity.update, relationship.create, and relationship.update. Entity operations are processed before relationship ones within a single call, and a relationship.create can resolve from/to by a name minted earlier in the same batch — but the entity write is queued, not applied inline, so the endpoint check that runs immediately before the relationship is written normally finds nothing yet and the operation fails with “Both source and target entities must exist and be owned by the user”. Create the entities in one call, then relate them in a second. A dryRun returns before that check and so reports the same-call pattern as succeeding.

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 allows only its own native-app origins by default (capacitor://localhost, ionic://localhost, and bare http://localhost and https://localhost). No browser page on any other origin can call these endpoints, so browser-based MCP clients and browser JavaScript do not work — treat this as a server-side and CLI integration. An operator can add origins with the CORS_ALLOWED_ORIGINS environment variable (comma-separated); it is empty out of the box. The allowed request headers are Content-Type, Authorization, X-CSRF-Token, and X-API-Key, and the only exposed response header is X-Thread-Id, so a browser cannot send or read Mcp-Session-Id even from an allowed origin.