RetrieveMemory Query Logging

GoodMem can persist curated logs for RetrieveMemory calls. These logs are intended for security review, compliance investigations, debugging, and retrieval-quality analysis where ordinary process logs are not enough.

This is separate from general server logging and proxy audit logging. RetrieveMemory query logging captures structured request and response envelopes for the retrieval pipeline itself.

How logging is enabled

Logging can be enabled in two ways:

The persisted row records its source as one of:

• CALLER_OPT_IN
• POLICY
• CALLER_OPT_IN_AND_POLICY

Logging is best effort. If the logging pipeline itself fails, GoodMem does not fail the user's request and records warnings in the normal server logs.

Caller opt-in

For REST POST /v1/memories:retrieve, add a logging block to the request body:

{
  "message": "What changed in the incident response process?",
  "spaceKeys": [
    {
      "spaceId": "30000000-0000-4000-8000-000000000301"
    }
  ],
  "logging": {
    "enabled": true,
    "callerAttributes": {
      "experiment": "incident_rag_v2",
      "cohort": 3,
      "canary": true
    }
  }
}

For REST GET /v1/memories:retrieve, use the query parameter:

curl \
  -H "x-api-key: gm_your_key" \
  "https://api.goodmem.ai/v1/memories:retrieve?message=What+changed%3F&spaceIds=30000000-0000-4000-8000-000000000301&loggingEnabled=true"

For gRPC, set RetrieveMemoryRequest.logging.enabled = true.

Caller attributes are optional flat scalar metadata that GoodMem attaches if the request is logged. Use them for experiment IDs, tenant routing hints, or other downstream slicing keys. They do not enable logging by themselves, so a request with callerAttributes but without enabled: true is not persisted unless an admin policy also matches.

This lets applications provide annotations without deciding whether the request should be logged:

{
  "message": "What changed in the incident response process?",
  "spaceKeys": [
    {
      "spaceId": "30000000-0000-4000-8000-000000000301"
    }
  ],
  "logging": {
    "enabled": false,
    "callerAttributes": {
      "experiment": "incident_rag_v2",
      "cohort": 3
    }
  }
}

If no admin policy matches, the request can still succeed but no retrieve-memory log row is written. If an admin policy matches, the persisted row records POLICY as the logging source and includes the validated caller attributes. Invalid caller attributes reject the request even when enabled is false or omitted.

Admin auto-logging policies

Administrators can create immutable policies that automatically enable logging for matching RetrieveMemory calls. Policies are useful when you need centralized coverage without modifying every caller.

Policies are OR'd together globally: if any active, non-deleted policy matches, the request is logged. Inside a policy:

• match_all=true matches every authenticated RetrieveMemory request while active.
• Otherwise, any_of contains one or more OR clauses.
• Populated dimensions inside one clause are AND'd.
• Values inside a repeated UUID dimension are OR'd.
• Label selectors are exact key/value matches and are AND'd.

Supported policy dimensions:

Space-based conditions are evaluated against the spaces that pass normal authorization checks. A policy does not grant access to spaces and cannot cause an unauthorized request to retrieve data.

Policy lifecycle

Policies are immutable after creation. To change a policy, delete it and create a replacement.

Deleting a policy tombstones it rather than physically removing it. Tombstoned policies no longer match future requests, but their administrative history remains available when listing with include_deleted.

Each policy can have:

• active_from: inclusive activation time, defaulting to creation time.
• active_until: exclusive deactivation time, omitted for no scheduled end.
• labels: operator labels for listing and administration.
• delete_reason: optional reason recorded when the policy is tombstoned.

Runtime nodes keep an in-memory policy snapshot. Policy creates and tombstones notify running nodes through PostgreSQL LISTEN/NOTIFY, and a slower reconciliation pass catches missed notifications. Create and delete calls do not wait for every node's local cache to reload before returning.

CLI examples

Create a temporary broad audit policy:

goodmem system retrieve-log-policy create \
  --display-name "Temporary retrieve audit" \
  --description "Incident review SEC-1234" \
  --match-all \
  --active-until "2026-07-01T00:00:00Z"

The CLI warns when --match-all is used because it can log every authenticated retrieval request while the policy is active.

Create a scoped policy for a specific user and space:

goodmem system retrieve-log-policy create \
  --display-name "Support space retrieval audit" \
  --requestor-user-id "10000000-0000-4000-8000-000000000301" \
  --space-id "30000000-0000-4000-8000-000000000301" \
  --label "owner=security" \
  --active-until "2026-07-01T00:00:00Z"

Create a scoped policy using labels:

goodmem system retrieve-log-policy create \
  --display-name "Production support API key audit" \
  --api-key-label "purpose=support" \
  --space-label "classification=restricted" \
  --label "owner=security"

List active policies at a specific instant:

goodmem system retrieve-log-policy list \
  --active-at "2026-06-15T00:00:00Z"

Delete a policy:

goodmem system retrieve-log-policy delete \
  "40000000-0000-4000-8000-000000000301" \
  --reason "Replaced by narrower policy"

REST policy example

Create a policy with REST:

curl -X POST "https://api.goodmem.ai/v1/admin/retrieve-memory-log-policies" \
  -H "x-api-key: gm_your_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Restricted space retrieval audit",
    "description": "Log support API keys reading restricted spaces",
    "condition": {
      "anyOf": [
        {
          "apiKeyLabelSelectors": {
            "purpose": "support"
          },
          "spaceLabelSelectors": {
            "classification": "restricted"
          }
        }
      ]
    },
    "labels": {
      "owner": "security"
    }
  }'

See the generated REST, gRPC, and CLI references for the full list of fields and flags.

What gets persisted

The durable log table stores one row per logged RetrieveMemory call, plus side tables for spaces and matched policies. At a high level, records include:

• request start, finish, and logged timestamps
• request UUID, trace ID, and span ID when available
• terminal outcome and gRPC status code/message when applicable
• authenticated requestor user ID and API key ID
• caller attributes, when the request supplied valid attributes and was logged by caller opt-in or admin policy
• curated request payload JSON
• curated response payload JSON
• duration and JSON payload size fields
• accessible space IDs that influenced retrieval
• matched policy IDs and policy display names

The stored payloads are curated JSON envelopes, not raw wire transcripts. Full memory-definition bodies are intentionally elided from response payloads to keep log rows bounded.

Reading logs

GoodMem exposes a public admin API for managing logging policies, but it does not yet provide a public API for querying the persisted log rows. To inspect logs directly, query the database tables:

• goodmem.retrieve_memory_log
• goodmem.retrieve_memory_log_space
• goodmem.retrieve_memory_log_policy_match

Permissions

Policy management requires admin permissions:

Normal RetrieveMemory authorization is unchanged. A logging policy decides whether to persist a record; it does not alter what the caller can read.

Related links

• Access Control — API keys and permission failures.
• Console Search — user-facing retrieval from the web console.
• MCP Server — agent-facing retrieval through goodmem_retrieve.
• Streaming Responses — RetrieveMemory event stream format.