feat(project): add project add memory

[notgitika]

This PR adds agentcore project add memory, which validates and appends a memory resource to spec.memories in agentcore.json. Memory resources do not scaffold any application files and are deployed through the generated CDK application.

Example:

  agentcore project add memory \
    --name UserFacts \
    --strategies SEMANTIC,EPISODIC

To maintain parity with the xisting CLI functionality, while also adding more configurability and customization, --strategies supports 2 input types:

• Comma-separated managed strategy types using default namespaces
• JSON MemoryStrategyInput[] for explicit names, descriptions, and namespaces (there is a parameter help in --help for ease of understanding for the user)

The command also supports expiry duration, indexed keys, stream delivery, encryption and execution roles, descriptions, and tags (description is a new optional field. Here is the CDK PR for it https://github.com/aws/agentcore-l3-cdk-constructs/pull/325 )

Callouts:

• CUSTOM strategies are not supported because their extraction configuration cannot yet be represented by the project schema.

Validation

I tested it myself e2e with different combinations, flags, strategy conversions and validation failures. It all works well. I also tested it with agetncore project build

TODO: check compatibility with harness resource

[codecov-commenter]

Codecov Report

❌ Patch coverage is 99.15254% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.17%. Comparing base (a41b4de) to head (1e902a7).
⚠️ Report is 1 commits behind head on refactor.

Files with missing lines	Patch %	Lines
src/handlers/project/add/memory/index.ts	99.12%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2025      +/-   ##
============================================
+ Coverage     97.15%   97.17%   +0.02%     
============================================
  Files           387      388       +1     
  Lines         23124    23360     +236     
============================================
+ Hits          22465    22699     +234     
- Misses          659      661       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[notgitika]

My agent ran focused testing for project add memory after the latest validation changes:

• 122 focused project tests pass, plus build/typecheck/lint/format
• Rebuilt CLI verified valid JSON persistence and atomic rejection for the new edge cases
• Covered strategy unions, unsupported fields, indexed keys, stream delivery, tags, malformed JSON, and boundary inputs
• Live AWS lifecycles passed for minimal memory, all four managed strategies, and Kinesis stream delivery (CREATE_COMPLETE followed by cleanup)
• Confirmed no test stacks, memories, or streams remain

The testing surfaced and we fixed empty shorthand entries, recursive unsupported-field stripping (including __proto__), missing JSON strategy names, and the JSON-object diagnostic. The remaining long default strategy-name boundary is in the existing project schema/CDK naming layer rather than this handler.

[nborges-aws]

LGTM thanks for updates!

[jariy17]

Why didn't we use zod.strictObject

[notgitika]

good suggestion!

[jariy17]

I feel like there is a lot going on here just for parse and converting strategy inputs. Maybe we should create an adapter like this

xport interface MemoryStrategyAdapter<TInput = unknown> {
    readonly type: MemoryStrategyType;
    readonly memberKey: string;
    readonly inputSchema: z.ZodType<TInput>;

    fromInput(input: TInput): MemoryStrategy;
    toInput(strategy: MemoryStrategy): TInput;

    fromShorthand?(): MemoryStrategy;
    canUseShorthand(strategy: MemoryStrategy): boolean;
  }

  The codec indexes registered adapters:

  export class MemoryStrategyFlagCodec {
    private readonly byType: Map<string, MemoryStrategyAdapter>;
    private readonly byMember: Map<string, MemoryStrategyAdapter>;

    constructor(adapters: readonly MemoryStrategyAdapter[]) {
      this.byType = new Map(
        adapters.map((adapter) => [adapter.type, adapter]),
      );
      this.byMember = new Map(
        adapters.map((adapter) => [adapter.memberKey, adapter]),
      );
    }

    parse(raw: string): MemoryStrategy[] {
      return raw.trimStart().startsWith("[")
        ? this.parseJson(raw)
        : this.parseShorthand(raw);
    }

    toFlag(strategies: readonly MemoryStrategy[]): string {
      const adapters = strategies.map((strategy) => {
        const adapter = this.byType.get(strategy.type);

        if (!adapter) {
          throw new InputValidationError(
            `Unsupported memory strategy '${strategy.type}'`,
          );
        }

        return adapter;
      });

      if (
        strategies.every((strategy, index) =>
          adapters[index].canUseShorthand(strategy),
        )
      ) {
        return strategies.map((strategy) => strategy.type).join(",");
      }

      return JSON.stringify(
        strategies.map((strategy, index) => {
          const adapter = adapters[index];

          return {
            [adapter.memberKey]: adapter.toInput(strategy),
          };
        }),
      );
    }

    private parseShorthand(raw: string): MemoryStrategy[] {
      return raw.split(",").map((value) => {
        const type = value.trim();
        const adapter = this.byType.get(type);

        if (!adapter?.fromShorthand) {
          throw new InputValidationError(
            `Unsupported shorthand strategy '${type}'`,
          );
        }

        return adapter.fromShorthand();
      });
    }

    private parseJson(raw: string): MemoryStrategy[] {
      const inputs = JSON.parse(raw) as unknown[];
      return inputs.map((input) => this.parseJsonMember(input));
    }

    private parseJsonMember(input: unknown): MemoryStrategy {
      // Validate that input is an object containing exactly one member.
      const [memberKey] = Object.keys(input as object);
      const adapter = this.byMember.get(memberKey);

      if (!adapter) {
        throw new InputValidationError(
          `Unsupported memory strategy member '${memberKey}'`,
        );
      }

      const value = adapter.inputSchema.parse(
        (input as Record<string, unknown>)[memberKey],
      );

      return adapter.fromInput(value);
    }
  }

  Registration is centralized:

  const strategyCodec = new MemoryStrategyFlagCodec([
    new StandardStrategyAdapter("SEMANTIC", "semanticMemoryStrategy"),
    new StandardStrategyAdapter(
      "SUMMARIZATION",
      "summaryMemoryStrategy",
    ),
    new StandardStrategyAdapter(
      "USER_PREFERENCE",
      "userPreferenceMemoryStrategy",
    ),
    new EpisodicStrategyAdapter(),
  ]);