Add GenAI memory operation conventions by nagkumar91 · Pull Request #140 · open-telemetry/semantic-conventions-genai

nagkumar91 · 2026-05-11T15:18:58Z

Summary

Migrates the narrowed GenAI memory operations proposal from open-telemetry/semantic-conventions#3250 into this repository.

Adds:

memory operation names: create_memory_store, search_memory, update_memory, delete_memory, delete_memory_store
memory spans for memory store lifecycle and memory record CRUD/search operations
attributes: gen_ai.memory.store.id, gen_ai.memory.record.id, gen_ai.memory.query.text, gen_ai.memory.records
docs/gen-ai/gen-ai-memory-records.json with content intentionally allowing any JSON value
Google ADK reference scenario coverage for upsert_memory and search_memory spans (matching ADK's add_session_to_memory / search_memory API surface); AWS Bedrock AgentCore scenario covers create_memory_store, create_memory, update_memory, search_memory, delete_memory, delete_memory_store
follow-up issue for memory search vs retrieval documents overlap: Clarify overlap between GenAI memory records and retrieval documents #139

Review feedback applied from old PR

Aligned gen_ai.memory.records YAML and JSON schema so record content can be any JSON value.
Kept JSON-schema property details in the JSON schema instead of duplicating them in the YAML note.
Backticked gen_ai.memory.store.id in registry guidance.
Removed the repeated explicit “do not capture by default” registry wording; span usage marks content-bearing attributes as opt-in.
Added reference scenario/report coverage under reference/.

Framework evidence

Framework	Memory operations represented	Evidence
Google ADK	Yes: add/search memory APIs	`BaseMemoryService` and `InMemoryMemoryService` define `add_session_to_memory`, `add_events_to_memory`, `search_memory`
AWS Bedrock AgentCore	Yes: create/retrieve/delete memory records	AgentCore memory quickstart uses memory record CRUD APIs
Azure AI Foundry	Yes: search/update/delete memory scopes	Azure AI Foundry agent memory concepts describe memory search, update, and scope deletion
Mem0	Yes: add/search/delete/delete_all memories	Mem0 docs show `add`, `search`, `delete`, and `delete_all`
CrewAI	Yes: remember/recall/forget memory model	CrewAI memory docs describe short-term, long-term, entity, and user memory behavior
Letta / MemGPT	Yes: archival memory insert/search and memory blocks	Letta docs describe archival memory and blocks

Validation

make generate-all
make check-policies
cd reference && uv run run-scenario google-adk
cd reference && uv run update-reports
cd reference && uv tool run --from ruff ruff check src/semconv_genai scenarios/google-adk
cd reference && uv tool run --from ruff ruff format --check src/semconv_genai scenarios/google-adk

Notes

This intentionally keeps the migrated scope narrow and leaves contentious overlap with gen_ai.retrieval.documents to follow-up issue #139.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Migrates the GenAI “memory operations” semantic conventions into this repo by adding new gen_ai.operation.name values, defining corresponding client spans and memory-related attributes (plus a JSON schema), and extending the reference scenario/reporting pipeline to demonstrate capturability (Google ADK scenario).

Changes:

Add new memory operation span definitions (create_memory_store, search_memory, update_memory, delete_memory, delete_memory_store) and memory attributes (gen_ai.memory.store.id, gen_ai.memory.record.id, gen_ai.memory.query.text, gen_ai.memory.records).
Introduce docs/gen-ai/gen-ai-memory-records.json schema and update generated docs tables/pages to include the new operations/attributes.
Extend reference scenario + reporting to cover Google ADK memory create/update/search spans and generate new span coverage reports.

Reviewed changes

Copilot reviewed 25 out of 26 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
reference/src/semconv_genai/semconv_model.py	Registers the new memory span types in the reference model loader.
reference/src/semconv_genai/report.py	Adds doc anchor links for the new memory span types in report output.
reference/src/semconv_genai/data_files.py	Adds memory span types to the reference report display order.
reference/scenarios/google-adk/scenario.py	Implements Google ADK memory create/update/search reference spans and attributes.
reference/scenarios/google-adk/data.json	Declares expected attributes observed for the new Google ADK memory span types.
reference/reports/update-memory-span.md	Adds generated reference coverage report page for `update_memory`.
reference/reports/search-memory-span.md	Adds generated reference coverage report page for `search_memory`.
reference/reports/delete-memory-store-span.md	Adds generated reference coverage report page for `delete_memory_store` (currently no supporting libs).
reference/reports/delete-memory-span.md	Adds generated reference coverage report page for `delete_memory` (currently no supporting libs).
reference/reports/create-memory-store-span.md	Adds generated reference coverage report page for `create_memory_store`.
reference/README.md	Lists the new memory span coverage reports in the reference index.
model/gen-ai/spans.yaml	Defines the new memory client span types and shared memory attribute group.
model/gen-ai/registry.yaml	Adds new `gen_ai.operation.name` values and memory attribute definitions (including schema linkage).
docs/registry/attributes/gen-ai.md	Updates generated attribute registry page to include new memory attributes/operation values.
docs/gen-ai/openai.md	Updates provider guidance docs to include new operation names in well-known lists.
docs/gen-ai/mcp.md	Updates MCP guidance docs to include new operation names in well-known lists.
docs/gen-ai/gen-ai-spans.md	Updates span documentation (including new memory span sections).
docs/gen-ai/gen-ai-metrics.md	Updates metric documentation to include new operation names in well-known lists.
docs/gen-ai/gen-ai-memory-records.json	Adds the JSON schema for `gen_ai.memory.records`.
docs/gen-ai/gen-ai-events.md	Updates event documentation to include new operation names in well-known lists.
docs/gen-ai/gen-ai-agent-spans.md	Updates agent span documentation to include new operation names in well-known lists.
docs/gen-ai/azure-ai-inference.md	Updates Azure AI Inference guidance docs to include new operation names in well-known lists.
docs/gen-ai/aws-bedrock.md	Updates AWS Bedrock guidance docs to include new operation names in well-known lists.
docs/gen-ai/anthropic.md	Updates Anthropic guidance docs to include new operation names in well-known lists.
CHANGELOG.md	Adds an Unreleased changelog entry for the new memory operation conventions.

Add the non-normative memory records model representation, align the committed JSON schema with it, and apply the memory store id wording nit. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Update the changelog link to the migrated GenAI PR and make create_memory_store set the memory store id whenever applicable. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Refresh generated markdown after resolving the registry documentation conflict. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Remove synthesized Google ADK memory store and record ids, and add AWS Bedrock AgentCore reference coverage for memory store lifecycle and record operations. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Relax provider name for memory spans, add memory record count, remove store IDs from memory span names, and document opt-in capture for sensitive memory content. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Add create_memory and upsert_memory operations, narrow update_memory to existing-record modifications, and update reference coverage for AgentCore and Google ADK. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Make content required inside emitted memory record JSON objects while keeping the gen_ai.memory.records attribute opt-in. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 32 out of 34 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (3)

reference/src/semconv_genai/semconv_model.py:1

The PR description lists memory operation names as create_memory_store, search_memory, update_memory, delete_memory, delete_memory_store, but the implementation also introduces create_memory and upsert_memory (and corresponding spans/reports). Please either update the PR description to include these operations or remove/defers these additions so the PR matches the stated scope.
reference/src/semconv_genai/semconv_model.py:1
The PR description lists memory operation names as create_memory_store, search_memory, update_memory, delete_memory, delete_memory_store, but the implementation also introduces create_memory and upsert_memory (and corresponding spans/reports). Please either update the PR description to include these operations or remove/defers these additions so the PR matches the stated scope.
docs/gen-ai/non-normative/models.ipynb:1
These fields default to None but are annotated as non-optional (str, dict[str, Any], float). This creates a type mismatch (and can cause runtime validation errors if None is ever passed explicitly). Prefer str | None, dict[str, Any] | None, and float | None for consistency with the defaults.

Update the GenAI spans TOC for create/upsert memory, clarify the changelog entry, and align AgentCore reference labels with memory store semantic operations. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Add generated create_memory and upsert_memory span sections and group memory spans under a Memory heading in the spans document. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Remove repeated span-name high-cardinality notes and simplify the memory store id attribute note now that store ids are not part of memory span names. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…-ops Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Replace per-operation memory span conventions with a single gen_ai.memory.client span keyed by gen_ai.operation.name, and update generated docs, schema snapshot, and reference reports. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Reformat gen-ai-memory-records.json with the notebook generator's 4-space JSON indentation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 26 out of 28 changed files in this pull request and generated 2 comments.

ADK's InMemoryMemoryService has no public store-lifecycle API and the constructor produces no library-owned store identifier, so wrapping it in a create_memory_store span did not credibly demonstrate the operation. create_memory_store remains covered by reference/scenarios/aws-bedrock-agentcore/ where the returned memoryId is captured directly from the SDK response. Also annotate the in-memory store_id derivation as 'derivable' per the evaluate-reference rubric: (app_name, user_id) is ADK's own internal scope key for InMemoryMemoryService.

…server routes The aws-bedrock-agentcore reference scenario wrapped every boto3 call in botocore.stub.Stubber, which intercepts before the HTTP transport. Per reference/README.md, each scenario must exercise the SDK against the deterministic local mock server, so server.address/server.port coverage came from client configuration alone rather than from an actual SDK request. Add a bedrock_agentcore mock-server blueprint that serves both the control plane (CreateMemory, DeleteMemory) and data plane (BatchCreateMemoryRecords, BatchUpdateMemoryRecords, RetrieveMemoryRecords, DeleteMemoryRecord) operations at the URL paths declared by the botocore service model, and strip Stubber from the scenario. Span attributes are unchanged (data.json diff is empty); they are now observed from real HTTP round trips.

Copilot

Pull request overview

Copilot reviewed 28 out of 30 changed files in this pull request and generated 7 comments.

…enario Address 7 comments from PR open-telemetry#140 review 4293190348. The mock previously accepted any memoryId/memoryRecordId, and the scenario used hardcoded constants disconnected from the IDs returned by create_memory and batch_create_memory_records, so the lifecycle spans did not demonstrate real continuity across operations. Scenario: - Drop MEMORY_ID and MEMORY_RECORD_ID constants. - run_create_memory_store_reference returns response['memory']['id']. - run_create_and_update_memory_reference returns the memoryRecordId from the batch_create response, used in the subsequent batchUpdate payload. - main() threads both IDs into search, delete_memory, and delete_memory_store so every span and SDK call references real state. Mock blueprint: - create_memory and delete_memory now own the _MEMORIES lifecycle. - delete_memory, batchCreate, batchUpdate, retrieve, and delete_memory_record return 404 when memory_id is not in _MEMORIES. - batchUpdate reports missing records in failedRecords with errorCode=404 instead of falsely claiming SUCCEEDED. - delete_memory_record returns 404 when the record is not present. data.json diff is empty; scenario passes end-to-end against the tightened mock.

Copilot

Pull request overview

Copilot reviewed 28 out of 30 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

Copilot reviewed 28 out of 30 changed files in this pull request and generated 1 comment.

trask

Thanks @nagkumar91!

Address review feedback by inlining memory span attributes and removing the custom memory schema default helper. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

`make generate-all` after rebasing onto main with the GenAI memory attributes (open-telemetry#140) renumbers all subsequent footnote references in docs/registry/attributes/gen-ai.md. The handoff attribute rows (gen_ai.agent.handoff.source.name, .target.name) added by this PR remain present and unchanged; only the numeric footnote indices on the surrounding rows shift.

Add GenAI memory operation conventions

e95a78d

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

nagkumar91 requested a review from a team as a code owner May 11, 2026 15:19

Copilot AI review requested due to automatic review settings May 11, 2026 15:19

Copilot started reviewing on behalf of nagkumar91 May 11, 2026 15:23 View session

Copilot AI reviewed May 11, 2026

View reviewed changes

Comment thread model/gen-ai/spans.yaml Outdated

Comment thread CHANGELOG.md Outdated

nagkumar91 and others added 2 commits May 11, 2026 08:48

Address memory records review feedback

7d409bb

Add the non-normative memory records model representation, align the committed JSON schema with it, and apply the memory store id wording nit. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Address memory PR review comments

baa1770

Update the changelog link to the migrated GenAI PR and make create_memory_store set the memory store id whenever applicable. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

trask mentioned this pull request May 11, 2026

gen-ai: semantic conventions for memory operations open-telemetry/semantic-conventions#3250

Closed

trask self-assigned this May 11, 2026

github-actions Bot mentioned this pull request May 11, 2026

Pull Request Dashboard #102

Closed

trask reviewed May 11, 2026

View reviewed changes

Comment thread reference/scenarios/google-adk/scenario.py

nagkumar91 and others added 2 commits May 11, 2026 11:37

Merge origin/main into memory proposal

fa4bc45

Refresh generated markdown after resolving the registry documentation conflict. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Add AgentCore memory reference coverage

85d937c

Remove synthesized Google ADK memory store and record ids, and add AWS Bedrock AgentCore reference coverage for memory store lifecycle and record operations. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

trask reviewed May 11, 2026

View reviewed changes

nagkumar91 and others added 4 commits May 12, 2026 10:35

Merge origin/main into memory proposal

a007480

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Address memory convention review feedback

9084ad3

Relax provider name for memory spans, add memory record count, remove store IDs from memory span names, and document opt-in capture for sensitive memory content. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Split memory record write operations

e9d1063

Add create_memory and upsert_memory operations, narrow update_memory to existing-record modifications, and update reference coverage for AgentCore and Google ADK. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Require memory record content

8b40879

Make content required inside emitted memory record JSON objects while keeping the gen_ai.memory.records attribute opt-in. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

trask requested a review from Copilot May 12, 2026 18:41

Copilot AI reviewed May 12, 2026

View reviewed changes

Comment thread reference/scenarios/aws-bedrock-agentcore/scenario.py Outdated

trask reviewed May 12, 2026

View reviewed changes

Comment thread docs/gen-ai/gen-ai-spans.md Outdated

Comment thread CHANGELOG.md Outdated

Address memory PR follow-up comments

a225a5b

Update the GenAI spans TOC for create/upsert memory, clarify the changelog entry, and align AgentCore reference labels with memory store semantic operations. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot started reviewing on behalf of trask May 12, 2026 19:46 View session

trask reviewed May 12, 2026

View reviewed changes

Comment thread docs/gen-ai/gen-ai-spans.md Outdated

Group memory span docs

00956dd

Add generated create_memory and upsert_memory span sections and group memory spans under a Memory heading in the spans document. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

trask reviewed May 13, 2026

View reviewed changes

Comment thread model/gen-ai/spans.yaml Outdated

Comment thread model/gen-ai/registry.yaml Outdated

Accept memory store id wording nits

9c758c1

Remove repeated span-name high-cardinality notes and simplify the memory store id attribute note now that store ids are not part of memory span names. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

trask reviewed May 13, 2026

View reviewed changes

Comment thread model/gen-ai/spans.yaml

Comment thread docs/gen-ai/gen-ai-spans.md Outdated

nagkumar91 and others added 2 commits May 14, 2026 11:04

Merge remote-tracking branch 'origin/main' into proposal/genai-memory…

676854e

…-ops Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

nagkumar91 and others added 2 commits May 14, 2026 11:48

Match memory record schema generator formatting

4beb7fd

Reformat gen-ai-memory-records.json with the notebook generator's 4-space JSON indentation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

gena_ai.memory.record.content delete_memory

b37dbe1

trask requested a review from Copilot May 14, 2026 19:39

Copilot started reviewing on behalf of trask May 14, 2026 19:39 View session

Copilot AI reviewed May 14, 2026

View reviewed changes

Comment thread reference/scenarios/google-adk/scenario.py Outdated

Comment thread reference/scenarios/aws-bedrock-agentcore/scenario.py Outdated

trask added 2 commits May 14, 2026 13:05

trask requested a review from Copilot May 14, 2026 20:22

Copilot started reviewing on behalf of trask May 14, 2026 20:22 View session

Copilot AI reviewed May 14, 2026

View reviewed changes

trask requested a review from Copilot May 14, 2026 20:46

Copilot started reviewing on behalf of trask May 14, 2026 20:46 View session

Copilot AI reviewed May 14, 2026

View reviewed changes

Comment thread reference/src/semconv_genai/mock_server/bedrock_agentcore.py Outdated

Comment thread reference/scenarios/aws-bedrock-agentcore/scenario.py

trask added 2 commits May 14, 2026 14:02

Reject unknown memoryId in agentcore retrieve mock route

b30f50b

Apply ruff format to bedrock_agentcore mock

f6d8a5c

trask requested a review from Copilot May 14, 2026 21:06

Copilot started reviewing on behalf of trask May 14, 2026 21:06 View session

Copilot AI reviewed May 14, 2026

View reviewed changes

Comment thread reference/scenarios/google-adk/scenario.py

trask approved these changes May 14, 2026

View reviewed changes

Merge branch 'main' into proposal/genai-memory-ops

5badfb2

lmolkova approved these changes May 18, 2026

View reviewed changes

Comment thread docs/gen-ai/non-normative/models.ipynb Outdated

Comment thread model/gen-ai/spans.yaml Outdated

Merge origin/main into memory proposal

0e60e34

Address review feedback by inlining memory span attributes and removing the custom memory schema default helper. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

lmolkova approved these changes May 19, 2026

View reviewed changes

trask enabled auto-merge May 19, 2026 15:15

trask added this pull request to the merge queue May 19, 2026

Merged via the queue into open-telemetry:main with commit be551f8 May 19, 2026
39 checks passed

trask mentioned this pull request May 27, 2026

Proposal: Semantic Conventions for Generative AI Memory Systems (gen_ai.memory.*) #200

Open

Conversation

nagkumar91 commented May 11, 2026 • edited by trask Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Review feedback applied from old PR

Framework evidence

Validation

Notes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

trask left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

nagkumar91 commented May 11, 2026 •

edited by trask

Loading