Skip to content
GOCUX
Documentation
GOCUX / Documentationapi reference

Reference: retrieve scoped memories

Retrieve approved context for an exact audience and query.

Retrieve approved context for an exact audience and query.

Practical procedure

  1. Choose scope and provide only its matching target: projectId for project or sessionRef for session; neither for user or company.
  2. Send query, classificationCeiling and a limit from 1 to 20 to /memories/retrieve.
  3. Inspect returned source and version context before using content in a new task. Preserve an empty result as empty rather than widening the audience automatically.

Keep memory within its approved audience

Memory Graph separates a proposed memory from an approved one. The four scopes are session, user, project and company; choose the narrowest audience that needs the information. A manual proposal includes its reason, source reference and checksum, classification, retention and expiry. Corrections create a new version rather than silently replacing the history that a prior decision referred to.

Contract example

Developer examples below describe routes on an authorized, configured GoCux control-plane base URL. They are request shapes or operation references, not claims that a particular public hostname exposes the API. Use the workspace for the corresponding human workflow; availability and permissions depend on the actual deployment.

POST /memories/retrieve — example request body

{
  "scope": "project",
  "projectId": "project-id",
  "query": "preferred review format",
  "classificationCeiling": "internal",
  "limit": 5
}

Inspect the result

Retrieve only memories that match the intended scope and query. Inspect their source and approval status before carrying them into a new task. A project memory supplies projectId and no sessionRef; a session memory supplies sessionRef and no projectId. User and company scopes carry neither target field.

What to keep explicit

Retrieval checks do not make an unapproved or expired memory available. A source reference from an older response is not a permanent access grant.

Handle incomplete and refused work

The retrieval limit is 1–20 and classificationCeiling is public or internal. An incorrect scope shape is refused. Decisions bind memoryVersionId and expectedRowVersion, so refresh after a conflict rather than approving a stale version. Deletion and retention can remove a previously available memory; a saved identifier is not a perpetual right to retrieve its content.

Bring this workflow into your workspace.

Set the scope. Review the evidence. Approve the steps that need it.

Open the workspace

Keep exploring