fix(migration): carry AgentCore memory ingestion into migration plans

[leon1418]

Cross-session AgentCore Memory designs need to choose an ingestion path and retain that choice in the migration plan. This change carries the selected API and its rationale through the shared design references and both GCP and Azure generation flows.

• Use IngestData when only extracted long-term records are needed; use CreateEvent when raw AgentCore events must remain retrievable or support branching. Confirm unknown retention requirements during Design.
• Include agentic_design.memory_ingestion in the canonical cross-session JSON examples, with explicit omission rules for stateless/session-only designs. Keep all vendored copies synchronized.
• Preserve the API, rationale, integration point, IAM requirements, strategy setup and extraction checks in migration activities. Distinguish semantic search, enumeration and inspection by a known record ID; accepted ingestion does not mean extraction is complete.
• In Azure, stop the file-only worker on a missing or invalid decision and return it to the main window without editing design inputs. Finalize memory guidance after all fragments, in the mixed-run guide or AI-only README, replacing stale generated memory sections.

The branch incorporates current main through 9ef371d4, including the move from GCP-local references to canonical shared/ai sources. No ingestion SDK implementation or deployment is added.

Validation

• OCR delegation, independent general review and repository review, followed by candidate verification and a complete final startups-hybrid-v1 gate with no remaining findings.
• Local registered suites: 151 Node tests; 361 Agent Advisor tests and 343 validator/policy tests per plugin; 15 fixture asserters per plugin.
• Formatting, Markdown lint, TypeScript checks, frontmatter checks, model-ID lint, pricing coverage, shared-copy checks, cross-plugin drift and whitespace checks.
• The final four-file correction was revalidated against the actual assembler parser and 42 explicitly source-derived scenarios. Unchanged test/source evidence was retained by hash rather than represented as a new test run.
• No live AWS ingestion, deployment or end-to-end LLM migration replay was performed.

Sources

• Direct ingestion guide
• IngestData API
• ListMemoryRecords, RetrieveMemoryRecords, and GetMemoryRecord

[leon1418]

[🤖 AI review 🤖]

Reviewed: full diff (2 files, 1 logical change) at head 1c45434.

What changed: The "Across sessions" row in Q24's memory-requirement table now mentions the new IngestData API as a direct long-term memory ingestion path, alongside the existing short-term-event extraction flow. Single-sentence addition in a markdown table cell, applied identically to both the advisor and migrate plugin copies.

Cross-plugin parity: ✅ Both copies are byte-identical (blob SHA 39628a43). Drift allowlist unchanged.

Findings: 0 mandatory blockers. 0 Nits.

The addition is factual (verified against the Sep 8 announcement URL), correctly scoped to the one cell where ingestion mechanics are relevant, and preserves the prior guidance as still valid. ayn-builds' FYI about IngestData not appearing in the design-ref files is worth tracking as a follow-up but is correctly non-blocking — those files describe architecture patterns, not API-level features.

CI: 8/8 SUCCESS. Approvals: 0. Mergeable: yes (pending approval).

[herosjourney]

Review — head 72c3d8a

Documentation-only (+72/−10, 5 references × 2 plugin trees). Verdict: approve with comments — one should-fix, one nit, nothing blocking.

What I ran (verify, not read)

• mise run build on a fresh detached worktree at 72c3d8a: PASS, exit 0 — markdownlint clean, dprint clean, frontmatter OK, fail 0 across DSL suites; checkov 244/0 (lower count than newer branches is just the older base, not a regression), gitleaks no leaks, grype no vulnerabilities.
• cross-plugin-drift.ts: OK (273 identical, 25 allowlisted).
• Twin byte-identity: all 5 changed files identical advisor ↔ migrate.
• Primary-source verification (fetched AWS docs): IngestData (requires bedrock-agentcore:IngestData; extractionConfig drives long-term strategies; async — "accepted for processing" ≠ "extraction complete"), ListMemoryRecords, RetrieveMemoryRecords, and the Sept 2026 direct-ingest launch — all confirmed real and accurately described. The "successful submission means accepted, not that extraction is complete" framing matches the API's async semantics.

Axes

• Cross-plugin parity: clear — byte-identical twins, no allowlist suppression.
• Propagation & data: clear and correct. The SSOT chain holds: agentic_design.memory_ingestion in aws-design-ai.json (producer, both design refs) → activity in generation-ai.json (generate-ai.md, with a completion-checklist assert) → AgentCore Memory guide subsection (generate-artifacts-docs.md, gated on the activity's presence, reading from generation-ai.json rather than directly from design — proper chaining). Reachability verified on both routing paths: the Harness gate harness_config.memory_type == "cross_session" matches the harness schema; the Strands gate strands_config.memory_service == true matches the Strands schema. Correct that Clarify records memory_requirement and Design maps it to harness_config.memory_type — no field-name drift.
• Security / contradictions / completeness / parsimony: clear. No IaC, no SDK execution, no credentials. SessionManager kept independent of ingestion (correctly stated). Optional-field discipline is right (omit for none/session).

Should-fix (in-diff, non-blocking) — the producer JSON skeleton omits the new field

generate-ai.md now consumes memory_ingestion and its checklist asserts it's preserved, and design-ref-*.md describe it in prose. But the canonical agentic_design JSON skeleton an author copies — the Strands block in design-ref-agentic-to-agentcore.md (lines ~169–192) and the harness_config block in design-ref-harness.md — does not include memory_ingestion. So an author following the copy-paste skeleton won't emit it, and generate-ai.md (the line: "If absent, return to the selected design reference to confirm … and record the API choice") will hit that fallback on every cross_session run. The guarantee then holds only via the recovery path, not by construction.

Suggested fix: add the field to the JSON skeleton in both design refs (both trees), e.g.

    "regional_fit": "available|preview|unavailable",
    "memory_ingestion": { "api": "IngestData|CreateEvent", "rationale": "why this path" },
    "warnings": []

with a trailing note that it's present only for cross_session (omitted for none/session), matching the prose already added above the skeleton.

Nit — retrieval-verb pairing

generate-ai.md verifies processed records with "ListMemoryRecords or RetrieveMemoryRecords." Both are real AgentCore operations, but they differ: ListMemoryRecords enumerates; RetrieveMemoryRecords does semantic search. To confirm a specific ingested record was extracted, RetrieveMemoryRecords / GetMemoryRecord is the precise verb, with ListMemoryRecords as the enumerate-and-scan fallback. Minor wording only.

Not verified

No live AWS ingestion, no end-to-end Design→Generate run, no model eval — consistent with the PR's own "documentation changes only" scope.

Net: technically accurate, well-propagated, byte-identical twins, gates green. The one worthwhile change is closing the producer-skeleton gap so the field is emitted by construction rather than recovered via the generate-ai.md fallback.

[leon1418]

@herosjourney Addressed both items from your review in fd97ec9e.

• Producer JSON: Both canonical design skeletons now include agentic_design.memory_ingestion with a valid API and rationale. Their memory flags consistently illustrate cross_session; adjacent rules explain how to omit the field for none/session and make clear that IngestData is not an unconditional default.
• Verification verbs: The plan now distinguishes semantic search with RetrieveMemoryRecords, paginated enumeration with ListMemoryRecords, and inspection of a known candidate with GetMemoryRecord. The record ID must come from List/Retrieve, since IngestData does not return one. Verification checks expected content and available metadata; a non-empty response or a semantic-search miss alone is insufficient evidence.

Validation: reproduced the previous omission and parsed/checked all four updated JSON skeletons; Markdown lint passed across 874 files, formatting passed, and cross-plugin drift plus git diff --check passed. All edits are mirrored, and the PR description is updated. No live AWS ingestion or end-to-end model evaluation was run.

GitHub CI on fd97ec9e: all 9 checks passed, including the full build.

[herosjourney]

Re-review at fd97ec9e (previous: 72c3d8a8). Delta: 1 commit, 5 files (identical set, both trees).

Prior finding	Status at head
Should-fix — producer JSON skeleton omits memory_ingestion	Fixed at fd97ec9e — re-probed: parsed both design-ref-agentic-to-agentcore.md and design-ref-harness.md JSON skeletons; both now carry memory_ingestion at agentic_design level with a valid api/rationale, plus the omission rule for none/session stated directly below each block.
Nit — retrieval-verb pairing (ListMemoryRecords vs RetrieveMemoryRecords)	Fixed at fd97ec9e — re-probed: generate-ai.md now distinguishes RetrieveMemoryRecords (semantic search), ListMemoryRecords (paginated enumeration), and GetMemoryRecord (inspect a known memoryRecordId). Re-verified GetMemoryRecord against the live AWS API reference — signature and error shape match what's described.

New in delta: none beyond the two fixes.

Verified at head: all 5 changed files byte-identical between advisor/ and migrate/; cross-plugin-drift.ts OK (273 identical, 25 allowlisted, unchanged); both JSON skeletons parse; git merge-tree against origin/main is clean.

Verdict: Approve — supersedes my prior "approve with comments." Both open items are closed; nothing outstanding.

[leon1418]

[🤖 AI review 🤖]

Updated and reviewed at fac30823.

The main-branch integration preserves the earlier fixes in the new shared canonical references and all GCP/Azure vendored copies. The independent general and repository reviews both found one additional interaction: Azure now loaded the shared ingestion decision but did not carry it into its folded plan writer. This is fixed in fac30823, including the main-window handoff for missing decisions and post-fragment guide/README assembly. The existing AI-only no-guide contract is preserved.

The final startups-hybrid-v1 gate is complete with no remaining findings. Local validation includes 151 Node tests, 361 Agent Advisor tests and 343 validator/policy tests per plugin, both fixture registries, formatting/types/frontmatter and mirror checks. The final correction also has actual parser checks and 42 source-derived regression scenarios. These scenarios are not live migration or AWS execution.

The previous reviewer requests remain addressed. Approval remains a user action; new-head CI and repository approval gates must pass before merge.

[jkzietz]

Heads up: the aws-startup-advisor plugin has a new home

The plugin now lives in the Agent Toolkit for AWS, merged to main earlier today:
https://github.com/aws/agent-toolkit-for-aws/tree/main/plugins/aws-startup-advisor

We are beginning plans to deprecate this repository, so that's the copy to build on going forward — changes landed here won't reach customers once distribution repoints. Please re-open this PR against aws/agent-toolkit-for-aws.

Porting your diff: paths move from advisor/plugins/aws-startup-advisor/… to plugins/aws-startup-advisor/…. Two differences to expect:

• The plugin declares a single MCP server there — aws-mcp, the unified AWS MCP Server — and pricing is cache-only, with no live lookup.
• The destination enforces markdownlint's default rule set, which this repo does not. MD036 (emphasis used as a heading) and MD059 (descriptive link text) are the two that usually need fixing.

Happy to help with the move if anything doesn't map cleanly.