Curate agent-scoped memory

Seed operating knowledge that one agent recalls for every user, by writing agent-scoped memories through the memory-api.

Prerequisites

• Memory enabled on the agent, and a reachable memory-api. The memory tutorial shows how to port-forward it and set MEMORY_API.
• If internalServiceAuth is on, a ServiceAccount bearer token for the calls. See the memory-api reference.

Create an agent-scoped memory

1. Look up the Workspace UID and the AgentRuntime UID. Both scope fields take UIDs, not names.

   export WORKSPACE_ID=$(kubectl get workspace <workspace> -o jsonpath='{.metadata.uid}')
   export AGENT_ID=$(kubectl -n <namespace> get agentruntime <agent> -o jsonpath='{.metadata.uid}')

2. Post the memory. The type and content values here are illustrative.

   curl -fsS -X POST "$MEMORY_API/api/v1/agent-memories" \
     -H 'Content-Type: application/json' \
     -d "{
       \"workspace_id\": \"$WORKSPACE_ID\",
       \"agent_id\": \"$AGENT_ID\",
       \"type\": \"fact\",
       \"content\": \"Escalate refund requests older than 60 days to a supervisor.\",
       \"confidence\": 1.0,
       \"expires_at\": \"2027-01-01T00:00:00Z\"
     }"

   type must be allowed in the agent tier. With no schema on the bound MemoryPolicy, that means general, fact, preference, observation or temporal_summary. GET /api/v1/memory/schema lists the types in force. expires_at is optional and must be in the future.

The response is 201 with the stored record under memory; note memory.id.

Agent-scoped writes are stamped operator_curated. Enterprise consolidation may cite them in a summary but cannot modify them.

Change or remove a memory

Each POST creates a new record; repeating about_kind and about_key does not update one in place. To change a memory, delete it and post the replacement.

curl -fsS -X DELETE "$MEMORY_API/api/v1/agent-memories/<id>?workspace=$WORKSPACE_ID&agent=$AGENT_ID"

Both query parameters are required. The call returns 400 for an id that belongs to a user or to a different agent.

Verify

List the agent’s memories:

curl -fsS "$MEMORY_API/api/v1/agent-memories?workspace=$WORKSPACE_ID&agent=$AGENT_ID"

The response contains memories and total, and your record appears with tier set to the agent tier. The list takes optional limit (default 20, maximum 100) and offset.

Then start a conversation with the agent as any user and ask about the topic. Retrieval returns agent-scoped records for every user of that agent.

Troubleshooting

The POST fails with 500 internal server error

A name was sent where a UID belongs. workspace_id and agent_id must be the Workspace and AgentRuntime UIDs; a name such as support-agent fails in the store and the API returns the generic 500, with no field named. Repeat step 1 and resend.

The POST is rejected with a schema error

type is not allowed in the agent tier. Check GET /api/v1/memory/schema, or the schema on the bound MemoryPolicy.

Related pages

• Curate institutional knowledge for knowledge shared by all agents.
• Memory API reference for every route and scope parameter.
• Memory tools for conversation and user-scoped writes.