Skip to main content
Version: 0.12.0

Using memory in your organization

Introduced 0.12.0

Once an operator has enabled memory, provisioned your organization, and turned on the MCP server (see Enable and configure memory), using memory is simple: you remember and recall, and the layer scopes everything to you automatically. You never name your organization or user in a request — they come from your token. This page is the end-user and client-integration view.

tip

Everything you remember is private to your organization and to you. A recall only ever returns your own memories within your organization. That scoping is automatic and non-overridable — see Memory tenancy and isolation.

Table of contents

Everything is scoped to you, automatically​

When you call a memory verb with your token, the layer pins the organization and user from your verified identity. You can still add your own sub-partitions — namespace, agent, session — but you cannot widen the scope past your own organization and user. Two consequences:

  • You don't send a tenant or user. Even if you do, a value that conflicts with your identity is rejected with 403. Omit them.
  • Recall is already private. A recall returns only memories you remembered, in your organization.

Cross-session persistence​

Memory is durable and outlives any single conversation or process. What you remember today is recallable next week, from a different session, a different agent, or a different client — as long as you authenticate as the same user in the same organization. Use the session scope dimension to organize memories by thread when you want to, but recall spans all your sessions by default (unless you narrow it with a session filter). This is the point of the layer: it bridges the gap when a context window compacts, a process restarts, or a new conversation begins.

Choosing your embedding model​

If your operator provisioned your organization with a menu of embedding models (allowed_models — see Enable and configure memory), you can pick which one your memories are embedded and recalled with. If they didn't, your organization has a single default model and this step doesn't apply — recall just works.

See what you're using and what you may choose:

GET /_plugins/_memory/model

The response reports your effective model and its vector dimension, plus the allowed_models your organization permits. Your org and user are filled in from your token:

{
  "org": "acme",
  "user": "analyst-7",
  "effective_model": "amazon.titan-embed-text-v2:0",
  "dimension": 1024,
  "allowed_models": [
    "amazon.titan-embed-text-v2:0",
    "intfloat/e5-large-v2"
  ]
}

Select one — by model id, from that allowed set:

PUT /_plugins/_memory/model
{ "model": "intfloat/e5-large-v2" }
{
  "org": "acme",
  "user": "analyst-7",
  "model": "intfloat/e5-large-v2",
  "dimension": 1024
}

Your selection is bound to you within your organization — both taken from your token, never the request body — so you can only set your own model, and only to one your organization allows (anything else is rejected with 400). Your pinned model gets its own physically isolated index, so what you remember afterward is embedded and recalled in that model's space. Selecting a model requires an authenticated user identity (memory_read_write grants both GET and PUT; memory_read grants the GET only).

note

Switching your model changes the space your new memories live in; memories you remembered under a previous model stay in that model's index until an operator runs a re-embed backfill for the organization (see Migrate memories to a new model).

A worked example (direct REST)​

Authenticate however your deployment is set up — an API key here (see API keys for memory), but a JWT bearer token works identically.

Remember a fact — no scope needed; your organization and user are implicit:

POST /_plugins/_memory/remember
Authorization: ApiKey azLThjJhLi4uLi4uOnNlY3JldA==
Content-Type: application/json

{
  "content": "The area of interest is the Port of Long Beach.",
  "fact_type": "semantic",
  "tags": { "topic": "aoi" }
}
{ "memory_id": "m-1f3a9c2e" }

Recall it later — in a completely separate session, as the same user:

POST /_plugins/_memory/recall
Authorization: ApiKey azLThjJhLi4uLi4uOnNlY3JldA==
Content-Type: application/json

{ "query": "which port are we analyzing?", "k": 5 }
{
  "took_millis": 7,
  "count": 1,
  "hits": [
    {
      "id": "m-1f3a9c2e",
      "memory": "The area of interest is the Port of Long Beach.",
      "fact_type": "semantic",
      "score": 0.83,
      "tags": { "topic": "aoi" }
    }
  ]
}

The full verb reference — remember, recall, forget, rollup, drift/check, stats, every field and response — is in Inference memory.

Connecting an agent over MCP​

Most teams don't call the verbs by hand — they let an agent do it. When the operator enables the MCP server (plugins.ml_commons.mcp_server_enabled: true), the memory tools are exposed at POST /_plugins/_ml/mcp, and any MCP-capable client can use them. The client authenticates as you, so the agent's memories are scoped to your organization and user just like a direct call.

Connect an MCP client​

Point your MCP-capable client (a coding assistant or IDE agent) at your cluster's MCP endpoint over the streamable-HTTP transport, and authenticate with your token. Most clients take an HTTP MCP server as a URL plus headers — for example:

URL:     https://your-cluster.example:9200/_plugins/_ml/mcp
Header:  Authorization: ApiKey azLThjJhLi4uLi4uOnNlY3JldA==

The agent now has remember/recall (and the other memory tools) available, all scoped to your identity. It can persist context across sessions — pick up a prior investigation, recall a stated goal, or record a decision — and none of it is visible to another organization or another user.

note

Use a token that carries the roles the agent needs and no more. An API key created with memory_read_write (limited by owner) is a good fit for an assistant that should read and write memory but not administer the cluster. See API keys for memory.

Keeping your memory healthy​

  • forget deletes memories in a scope (pinned ones survive by default). A non-empty scope is required, so you can't accidentally wipe everything.
  • rollup consolidates aged memories into a summary to keep the store small — usually run by an operator or a scheduled job, not by you.
  • drift/check scores a response against your session's stated goal to keep a long agent run on-topic.

All three, with fields and responses, are in Inference memory.

Checking your own usage​

You can see your organization's own footprint and embedding usage at any time — no admin role needed (memory_read is enough):

GET /_plugins/_memory/usage

It reports your organization's stored document counts and on-disk size, the provider calls and tokens your embeddings billed, and how much content (if any) left the cluster to a managed embedding service. The scope is your own organization, taken from your token. See Monitoring memory usage and data residency.