Blocks and user profiles
Pin information the agent should see in every task with memory blocks, and keep per-end-user profiles that join the context when a userId is given.
Besides the memories found by search, there is information the agent should see in every task: the project's tech stack, coding conventions, a customer's general profile. Agent Memory offers two structures for this.
| Structure | Scope | When does it enter the context? |
|---|---|---|
| Memory block | Workspace (optional application and agent scope) | On every search, regardless of the query. |
| User profile | Workspace + end user (userId) | When userId is given in a search. |
Both are plain text maintained by hand (or by the agent): they are not embedded and do not go through duplicate checking or consolidation.
Memory blocks
A block consists of a label (label) and a value (value); e.g. tech_stack, coding_conventions, architecture. The default character limit is 2000. agentScope: "*" is for all agents; if a specific agent name is given, the block enters only that agent's context.
# Read
curl -s "$API/v1/blocks/$WS" -H "Authorization: Bearer $KEY"
# Write the whole block
curl -s -X PUT "$API/v1/blocks/$WS" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
-d '{"label":"tech_stack","value":".NET 10, PostgreSQL 17, Redis 7","agentScope":"*"}'
# Edit line by line
curl -s -X POST "$API/v1/blocks/$WS/curate" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
-d '{"label":"tech_stack","action":"replace","match":"Redis 7","value":"Redis 7 (session layer only)"}'curate actions:
action | Requires | Effect |
|---|---|---|
add | value | Appends a new line at the end. |
replace | match, value | Replaces the line containing match (case-insensitive substring). |
remove | match | Deletes the matching line. |
MCP: get_blocks(agentId?), curate_block(label, action, match?, value?). In the console, blocks are edited from the project's maintenance page.
Permissions: reading needs read; PUT needs write; curate needs curate. Blocks marked read-only cannot be changed. Blocks also go through content scanning; suspicious content causes the write to be rejected.
Tip
Because blocks enter every context, they take their share of the token budget first. Keep them short and current; write detailed information as regular memories.
User profiles
A profile is a single piece of text for one end user within a workspace (optionally an application), at most 2000 characters by default.
curl -s -X PUT "$API/v1/memory/users/$WS/demo-user/profile" \
-H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
-d '{"content":"Preferred language: Turkish. Report format: PDF. Meeting day: Wednesday."}'
# {"status":"updated"}
curl -s "$API/v1/memory/users/$WS/demo-user/profile" -H "Authorization: Bearer $KEY"
curl -s -X DELETE "$API/v1/memory/users/$WS/demo-user/profile" -H "Authorization: Bearer $KEY"- When
userId: "demo-user"is given in a search, the profile is added to the context in theuserProfilefield. - MCP:
get_user_profile(userId). - Your credential must have permission to act on behalf of this user (act for users).
Automatic enrichment (optional)
If the userProfile.autoEnrich setting is on, preference facts that carry a userId are added to the profile as lines during consolidation. The memory each line came from is tracked; when that memory is deleted, its line in the profile is deleted too. The setting is off by default.
Profile schema
A profile is free text; defining a specific JSON schema or updating individual fields is not supported. If you need structured fields, your application can write the text in its own format (e.g. Key: value lines).
Related pages
Consolidation, episodes and procedures
How consolidation turns a run's memories into episodes, facts and procedures, resolves contradictions, and learns from repeated success.
File summaries
Store short per-file summaries and structural information so coding agents can find the right file without rereading the repository.