Skip to content
agentics.you
Start free

Docs

Scoping: workspaces, namespaces and owners

Scope decides which memories a caller can read and where a new memory goes. There are three levels: the workspace, the namespace, and the owner recorded on each memory.

Workspace

Every memory belongs to exactly one workspace, the account your team signs in to. Nothing reads across workspaces. Every query is filtered by workspace in the database itself, with row-level security, so a bug in a caller cannot widen it.

Namespaces

On the REST API, a workspace is split into namespaces. A namespace is a named bucket of memories, such as one per customer, project or environment.

  • Every workspace has a default namespace. A write that names no namespace goes there.
  • POST /v1/memories takes namespace, either the namespace id or its name.
  • GET /v1/memories takes namespace_id, one id or several separated by commas.
  • Only a workspace admin, signed in, can create, rename or delete a namespace. The default namespace cannot be deleted. A namespace that still holds memories cannot be deleted unless you pass move_to with another namespace.
bash
curl https://agentics.you/v1/namespaces \
  -H "Authorization: Bearer $AGENTICS_API_KEY"

Keys are bound to namespaces

An API key from the console starts ak_. It reaches only the namespaces it is bound to.

  • A key with no namespaces is denied every request with key_has_no_namespaces.
  • A request for a namespace outside the key's binding answers namespace_out_of_scope.
  • A key can never create, rename or delete a namespace. A signed-in admin sets a key's namespaces with PUT /v1/keys/{key_id}/namespaces.
  • A signed-in person in the console sees every namespace in the workspace.

The owner on each memory

Each memory records who wrote it in provenance: user_id, agent_id, app_id and run_id. The server fills these from the caller. A request body cannot set them.

  • A signed-in person writing from the console is the user_id.
  • A key that sends an agent identity is the agent_id.
  • app_id and run_id are in the record and can be filtered on. No caller sets them yet.

GET /v1/memories filters on each of them by exact match: user_id, agent_id, app_id and run_id.

Scope on the MCP server

An MCP connection acts as one agent. The sign-in or the agent key names it, and the server never takes an agent from the request.

  • An agent reads memories in its workspace that are visible to the whole workspace, plus memories kept for a team it belongs to.
  • Where a memory is placed follows the agent's settings, not an argument on the call. A tool call cannot make a team memory visible to the whole workspace.
  • An agent marked as a contractor does not see memories marked redacted.
  • What a connection can call is set by its scopes. Recall needs receipts:read. Writing needs actions:record. See the MCP tool reference.