thinkwork-cli 0.5.1 → 0.5.3

package/dist/terraform/examples/greenfield/main.tf

@@ -72,10 +72,10 @@ variable "database_engine" {
   default     = "aurora-serverless"
 }
 
-variable "memory_engine" {
-  description = "Memory engine: 'managed' (AgentCore built-in, default) or 'hindsight' (ECS+ALB, opt-in)"
-  type        = string
-  default     = "managed"
+variable "enable_hindsight" {
+  description = "Optional Hindsight add-on alongside the always-on managed memory (ECS+ALB for semantic + graph retrieval)"
+  type        = bool
+  default     = false
 }
 
 variable "google_oauth_client_id" {
@@ -119,7 +119,7 @@ module "thinkwork" {
 
   db_password                = var.db_password
   database_engine            = var.database_engine
-  memory_engine              = var.memory_engine
+  enable_hindsight           = var.enable_hindsight
   google_oauth_client_id     = var.google_oauth_client_id
   google_oauth_client_secret = var.google_oauth_client_secret
   pre_signup_lambda_zip      = var.pre_signup_lambda_zip
@@ -199,16 +199,21 @@ output "database_name" {
   value       = module.thinkwork.database_name
 }
 
-output "memory_engine" {
-  description = "Active memory engine (managed or hindsight)"
-  value       = module.thinkwork.memory_engine
+output "hindsight_enabled" {
+  description = "Whether the Hindsight add-on is enabled"
+  value       = module.thinkwork.hindsight_enabled
 }
 
 output "hindsight_endpoint" {
-  description = "Hindsight API endpoint (null when memory_engine = managed)"
+  description = "Hindsight API endpoint (null when enable_hindsight = false)"
   value       = module.thinkwork.hindsight_endpoint
 }
 
+output "agentcore_memory_id" {
+  description = "AgentCore Memory resource ID used for automatic retention"
+  value       = module.thinkwork.agentcore_memory_id
+}
+
 output "admin_url" {
   description = "Admin app URL"
   value       = "https://${module.thinkwork.admin_distribution_domain}"

package/dist/terraform/examples/greenfield/terraform.tfvars.example

@@ -12,10 +12,13 @@ account_id = "123456789012"  # your AWS account ID
 #   "rds-postgres"      — Standard RDS PostgreSQL (dev/test, cheaper, deletion protection off)
 database_engine = "rds-postgres"
 
-# Memory engine:
-#   "managed"   — AgentCore built-in long-term memory (default, no extra infra)
-#   "hindsight" — Hindsight ECS+ALB service (opt-in, adds retain/recall/reflect tools)
-memory_engine = "managed"
+# Memory:
+#   AgentCore managed memory is always on — every agent gets automatic
+#   per-turn retention with zero config. Uncomment the line below to
+#   enable Hindsight as an optional add-on (adds an ECS+ALB service for
+#   semantic + entity-graph + cross-encoder retrieval tools alongside the
+#   built-in remember/recall/forget tools).
+# enable_hindsight = true
 
 # Database master password — use a strong password
 db_password = "CHANGE_ME_strong_password_here"

package/dist/terraform/modules/app/agentcore-memory/README.md

@@ -0,0 +1,77 @@
+# AgentCore Memory — App Module
+
+Provisions an AWS Bedrock AgentCore Memory resource with the four strategies
+the thinkwork Strands agent container uses for automatic retention:
+
+| Strategy    | Namespace template           | Purpose                                  |
+|-------------|------------------------------|------------------------------------------|
+| semantic    | `assistant_{actorId}`        | Cross-thread facts about the user        |
+| preferences | `preferences_{actorId}`      | User-stated preferences                  |
+| summaries   | `session_{sessionId}`        | Per-thread rolling summaries             |
+| episodes    | `episodes_{actorId}/{sessionId}` | Episodic memory of past interactions |
+
+Automatic retention is wired in the agent container: every turn emits a
+`CreateEvent` via `memory.store_turn_pair`, and AgentCore's background
+strategies extract facts into the namespaces above. Agents can read them
+back via the `recall()` tool (also always registered). There is no need for
+the model to call `remember()` explicitly — it only exists for user-driven
+"please remember X" requests.
+
+## Usage
+
+```hcl
+module "agentcore_memory" {
+  source = "../app/agentcore-memory"
+
+  stage  = var.stage
+  region = var.region
+  # Optional: skip provisioning and reuse an existing memory resource
+  # existing_memory_id = "my-pre-existing-memory-id"
+}
+
+module "agentcore" {
+  source              = "../app/agentcore-runtime"
+  # ...
+  agentcore_memory_id = module.agentcore_memory.memory_id
+}
+```
+
+## Why a shell script and not a first-class resource?
+
+The AWS Terraform provider does not (yet) expose a
+`aws_bedrockagentcore_memory` resource. Until it does, this module drives
+the lifecycle through the `aws bedrock-agentcore-control` CLI:
+
+- **Create/find**: `data "external"` runs `scripts/create_or_find_memory.sh`,
+  which is idempotent — it looks up an existing memory by name before
+  creating a new one. Safe to re-run.
+- **Destroy**: a paired `terraform_data` resource has a destroy-time
+  `local-exec` that calls `delete-memory` on the ID captured during create.
+
+When the AWS provider adds a native resource, migrate by importing the
+existing memory ID into the new resource and removing this module's
+external data source.
+
+## Requirements
+
+- `aws` CLI v2 with `bedrock-agentcore-control` commands (recent versions)
+- `jq` in PATH
+- IAM permissions:
+  - `bedrock-agentcore-control:ListMemories`
+  - `bedrock-agentcore-control:CreateMemory`
+  - `bedrock-agentcore-control:DeleteMemory`
+
+## Cost
+
+AgentCore Memory charges per CreateEvent and per memory record extracted.
+With automatic retention enabled, cost scales roughly linearly with chat
+volume. Budget accordingly before enabling in production.
+
+## Migration notes
+
+- **Strategies are immutable after creation.** If you need to change a
+  namespace template, you must delete and recreate the memory (losing all
+  records). Version the `name_prefix` or `stage` if you need to keep the
+  old records around during migration.
+- **BYO memory**: pass `existing_memory_id = "..."` to skip provisioning
+  entirely. Useful for shared memory across multiple stages.

package/dist/terraform/modules/app/agentcore-memory/main.tf

@@ -0,0 +1,159 @@
+################################################################################
+# AgentCore Memory — App Module
+#
+# Provisions an AWS Bedrock AgentCore Memory resource with the four strategies
+# the Strands agent container expects (semantic, preferences, summaries,
+# episodes). The resource is always created — AgentCore managed memory is
+# on by default so every agent gets automatic per-turn retention into
+# semantic / preference / summary / episode strategies without any tool-
+# calling by the model.
+#
+# **Why not a first-class resource?** The AWS provider does not (yet) expose a
+# `aws_bedrockagentcore_memory` resource type. Until it does, we drive the
+# create/find/destroy lifecycle through the `aws bedrock-agentcore-control`
+# CLI via a small shell script, and read the resulting memory ID back into
+# Terraform via `data "external"`. The script is idempotent — it lists
+# existing memories with the same name and returns the existing ID if found,
+# which keeps `terraform apply` safe to re-run.
+#
+# **BYO override:** If you already have an AgentCore Memory resource, set
+# `var.existing_memory_id` to skip provisioning. The module output will echo
+# that ID directly and no CLI calls are made.
+################################################################################
+
+terraform {
+  required_providers {
+    external = {
+      source  = "hashicorp/external"
+      version = ">= 2.3.0"
+    }
+  }
+}
+
+variable "stage" {
+  description = "Deployment stage (dev, prod, etc.) — used to name the memory resource"
+  type        = string
+}
+
+variable "name_prefix" {
+  description = "Prefix for the Bedrock AgentCore Memory resource name"
+  type        = string
+  default     = "thinkwork"
+}
+
+variable "existing_memory_id" {
+  description = "Optional pre-existing AgentCore Memory ID. When set, the module skips provisioning and passes this ID through."
+  type        = string
+  default     = ""
+}
+
+variable "region" {
+  description = "AWS region"
+  type        = string
+}
+
+variable "account_id" {
+  description = "AWS account ID"
+  type        = string
+  default     = ""
+}
+
+locals {
+  memory_name = "${replace(var.name_prefix, "-", "_")}_${replace(var.stage, "-", "_")}"
+  bootstrap   = var.existing_memory_id == ""
+}
+
+################################################################################
+# IAM Role for custom memory strategies
+################################################################################
+
+resource "aws_iam_role" "memory_execution" {
+  count = local.bootstrap ? 1 : 0
+  name  = "thinkwork-${var.stage}-memory-execution"
+
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect    = "Allow"
+      Principal = { Service = "bedrock-agentcore.amazonaws.com" }
+      Action    = "sts:AssumeRole"
+    }]
+  })
+}
+
+resource "aws_iam_role_policy" "memory_execution" {
+  count = local.bootstrap ? 1 : 0
+  name  = "memory-execution"
+  role  = aws_iam_role.memory_execution[0].id
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect   = "Allow"
+      Action   = ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream"]
+      Resource = "arn:aws:bedrock:${var.region}::foundation-model/*"
+    }]
+  })
+}
+
+################################################################################
+# Create-or-find via shell script (only when no existing_memory_id was given).
+#
+# The script produces JSON: `{"memory_id": "..."}`. Terraform re-runs it on
+# every plan — if the memory already exists, the script returns the same ID
+# without side effects. Inputs are passed as JSON on stdin; outputs MUST be
+# a single JSON object on stdout for `data "external"` to parse.
+################################################################################
+
+data "external" "memory" {
+  count   = local.bootstrap ? 1 : 0
+  program = ["bash", "${path.module}/scripts/create_or_find_memory.sh"]
+
+  query = {
+    name               = local.memory_name
+    region             = var.region
+    execution_role_arn = aws_iam_role.memory_execution[0].arn
+  }
+}
+
+################################################################################
+# Destroy-time cleanup
+#
+# Terraform's `data "external"` has no destroy hook, so we use a paired
+# `terraform_data` resource with a destroy-time local-exec that deletes the
+# memory by ID. `triggers_replace` binds the resource to the memory ID so
+# that replacing one memory correctly destroys the old one.
+################################################################################
+
+resource "terraform_data" "memory_lifecycle" {
+  count = local.bootstrap ? 1 : 0
+
+  input = {
+    memory_id = data.external.memory[0].result.memory_id
+    region    = var.region
+  }
+
+  triggers_replace = [
+    local.memory_name,
+    var.region,
+  ]
+
+  provisioner "local-exec" {
+    when    = destroy
+    command = "aws bedrock-agentcore-control delete-memory --region ${self.output.region} --memory-id ${self.output.memory_id} || echo 'delete-memory failed (may already be gone)'"
+  }
+}
+
+################################################################################
+# Outputs
+################################################################################
+
+output "memory_id" {
+  description = "Bedrock AgentCore Memory resource ID — passed into the agent container as AGENTCORE_MEMORY_ID"
+  value       = local.bootstrap ? data.external.memory[0].result.memory_id : var.existing_memory_id
+}
+
+output "memory_name" {
+  description = "Logical name used for the memory resource"
+  value       = local.memory_name
+}

package/dist/terraform/modules/app/agentcore-memory/scripts/create_or_find_memory.sh

@@ -0,0 +1,212 @@
+#!/usr/bin/env bash
+################################################################################
+# create_or_find_memory.sh
+#
+# Idempotent create-or-find for a Bedrock AgentCore Memory resource, plus
+# drift-correction for the strategy list on already-existing resources.
+#
+# Input (stdin, JSON):
+#   {"name": "<logical name>", "region": "<aws-region>",
+#    "execution_role_arn": "<optional>"}
+# Output (stdout, JSON): {"memory_id": "<resource-id>"}
+#
+# Behavior:
+#   1. Lists existing memories via `aws bedrock-agentcore-control list-memories`
+#      and matches by exact `name` OR by ID starting with `name-` (the API
+#      uses `{name}-{randomSuffix}` for the resource ID, and `name` sometimes
+#      comes back null on existing resources).
+#   2. If a match exists: get-memory, diff its current strategies against the
+#      desired set, and call update-memory with addMemoryStrategies for any
+#      that are missing. This lets us add new strategies to an existing
+#      memory without destructive recreation.
+#   3. If no match: create-memory with the full desired strategy list.
+#
+# Strategy set must match memory.py:STRATEGY_NAMESPACES exactly so the
+# agent container's recall() finds records written by the extractors:
+#   semantic     -> assistant_{actorId}
+#   preferences  -> preferences_{actorId}
+#   summaries    -> session_{sessionId}
+#   episodes     -> episodes_{actorId}/{sessionId}   (built-in episodicMemoryStrategy)
+#
+# Called from terraform/modules/app/agentcore-memory/main.tf via
+# `data "external"`. Keep stdout strictly JSON — any stray echo will break
+# Terraform's JSON parser. All diagnostics go to stderr.
+################################################################################
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Input
+# ---------------------------------------------------------------------------
+
+input="$(cat)"
+name="$(echo "$input" | jq -r '.name // empty')"
+region="$(echo "$input" | jq -r '.region // empty')"
+execution_role_arn="$(echo "$input" | jq -r '.execution_role_arn // empty')"
+
+if [[ -z "$name" || -z "$region" ]]; then
+  echo '{"error": "name and region are required"}' >&2
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Desired strategy set
+#
+# The full list passed to create-memory. Each entry is also a valid item
+# for update-memory's addMemoryStrategies list, so we can reuse the same
+# shape for drift correction. `episodes` uses the built-in
+# `episodicMemoryStrategy` type (NOT customMemoryStrategy — that was the
+# bug that silently dropped episodes on the first deploy).
+#
+# IMPORTANT: episodicMemoryStrategy REQUIRES a reflectionConfiguration whose
+# namespace is a prefix of the episodic namespace. If omitted, the API
+# synthesizes a default reflection namespace of
+# `/strategies/{memoryStrategyId}/actors/{actorId}/` which is NOT a prefix
+# of our flat `episodes_{actorId}/{sessionId}` template, and update-memory
+# fails with ValidationException. We set it to `episodes_{actorId}/` which
+# IS a prefix and gives cross-session reflection records a stable home.
+# ---------------------------------------------------------------------------
+
+strategies_json='[
+  {
+    "semanticMemoryStrategy": {
+      "name": "semantic",
+      "namespaces": ["assistant_{actorId}"]
+    }
+  },
+  {
+    "userPreferenceMemoryStrategy": {
+      "name": "preferences",
+      "namespaces": ["preferences_{actorId}"]
+    }
+  },
+  {
+    "summaryMemoryStrategy": {
+      "name": "summaries",
+      "namespaces": ["session_{sessionId}"]
+    }
+  },
+  {
+    "episodicMemoryStrategy": {
+      "name": "episodes",
+      "namespaces": ["episodes_{actorId}/{sessionId}"],
+      "reflectionConfiguration": {
+        "namespaces": ["episodes_{actorId}/"]
+      }
+    }
+  }
+]'
+
+# Map logical strategy name -> the top-level key used in the create/update
+# payload. Used to drift-correct existing memory resources by picking out
+# the entries whose names don't yet exist.
+desired_names=("semantic" "preferences" "summaries" "episodes")
+
+# ---------------------------------------------------------------------------
+# Step 1: look for an existing memory with this name
+# ---------------------------------------------------------------------------
+
+existing_id="$(
+  aws bedrock-agentcore-control list-memories \
+    --region "$region" \
+    --output json 2>/dev/null \
+    | jq -r --arg n "$name" '.memories[]? | select(.name == $n or (.id | startswith($n + "-"))) | .id' \
+    | head -n1 || true
+)"
+
+if [[ -n "$existing_id" && "$existing_id" != "null" ]]; then
+  # ---------------------------------------------------------------------------
+  # Step 2a: memory exists — drift-correct its strategy list
+  #
+  # Fetch current strategies, compute the set of desired strategy names that
+  # don't already exist, and call update-memory with addMemoryStrategies for
+  # the missing ones. This is idempotent — if everything matches, we call
+  # nothing and just return the existing ID.
+  # ---------------------------------------------------------------------------
+  current_names="$(
+    aws bedrock-agentcore-control get-memory \
+      --region "$region" \
+      --memory-id "$existing_id" \
+      --output json 2>/dev/null \
+      | jq -r '.memory.strategies[]? | .name'
+  )"
+
+  missing=()
+  for d in "${desired_names[@]}"; do
+    if ! grep -qxF "$d" <<<"$current_names"; then
+      missing+=("$d")
+    fi
+  done
+
+  if [[ ${#missing[@]} -gt 0 ]]; then
+    echo "[create_or_find_memory] existing memory $existing_id is missing strategies: ${missing[*]}" >&2
+
+    # Build the addMemoryStrategies list from the entries in strategies_json
+    # whose .name field matches a missing strategy.
+    add_json="$(
+      echo "$strategies_json" \
+        | jq --argjson wanted "$(printf '%s\n' "${missing[@]}" | jq -R . | jq -s .)" '
+            map(
+              select(
+                (.semanticMemoryStrategy.name // .userPreferenceMemoryStrategy.name //
+                 .summaryMemoryStrategy.name // .episodicMemoryStrategy.name //
+                 .customMemoryStrategy.name) as $n
+                | $wanted | index($n)
+              )
+            )
+          '
+    )"
+
+    update_payload="$(jq -nc --argjson add "$add_json" '{addMemoryStrategies: $add}')"
+
+    # update-memory takes memory-strategies as a structured object with
+    # add/modify/delete lists.
+    if aws bedrock-agentcore-control update-memory \
+        --region "$region" \
+        --memory-id "$existing_id" \
+        --memory-strategies "$update_payload" \
+        --output json >/dev/null 2>&1; then
+      echo "[create_or_find_memory] added missing strategies to $existing_id" >&2
+    else
+      # Capture the error for diagnostics but don't fail the whole apply —
+      # retention on the existing strategies still works.
+      err="$(aws bedrock-agentcore-control update-memory \
+        --region "$region" \
+        --memory-id "$existing_id" \
+        --memory-strategies "$update_payload" 2>&1 || true)"
+      echo "[create_or_find_memory] WARNING: update-memory failed: $err" >&2
+    fi
+  fi
+
+  jq -nc --arg id "$existing_id" '{memory_id: $id}'
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Step 2b: no existing memory — create one with the full strategy set
+# ---------------------------------------------------------------------------
+
+role_arg=""
+if [[ -n "$execution_role_arn" ]]; then
+  role_arg="--memory-execution-role-arn $execution_role_arn"
+fi
+
+create_output="$(
+  aws bedrock-agentcore-control create-memory \
+    --region "$region" \
+    --name "$name" \
+    --memory-strategies "$strategies_json" \
+    --event-expiry-duration 365 \
+    $role_arg \
+    --output json
+)"
+
+new_id="$(echo "$create_output" | jq -r '.memory.id // .id')"
+
+if [[ -z "$new_id" || "$new_id" == "null" ]]; then
+  echo '{"error": "create-memory returned no id"}' >&2
+  echo "create-memory output was: $create_output" >&2
+  exit 1
+fi
+
+jq -nc --arg id "$new_id" '{memory_id: $id}'

package/dist/terraform/modules/app/agentcore-runtime/main.tf

@@ -26,20 +26,14 @@ variable "bucket_name" {
   type        = string
 }
 
-variable "memory_engine" {
-  description = "Memory engine: 'managed' or 'hindsight'. Passed as MEMORY_ENGINE env var to the container."
-  type        = string
-  default     = "managed"
-}
-
 variable "hindsight_endpoint" {
-  description = "Hindsight API endpoint (only used when memory_engine = 'hindsight')"
+  description = "Hindsight API endpoint. Empty string (default) disables Hindsight tools in the container; set to an endpoint URL to enable Hindsight as an add-on alongside the always-on managed memory."
   type        = string
   default     = ""
 }
 
 variable "agentcore_memory_id" {
-  description = "AgentCore Memory resource ID (only used when memory_engine = 'managed')"
+  description = "AgentCore Memory resource ID. Populated automatically by the agentcore-memory module; injected into the container as AGENTCORE_MEMORY_ID for auto-retention."
   type        = string
   default     = ""
 }
@@ -120,6 +114,25 @@ resource "aws_iam_role_policy" "agentcore" {
         Action   = ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream", "bedrock:InvokeAgent"]
         Resource = "arn:aws:bedrock:${var.region}::foundation-model/*"
       },
+      {
+        # Automatic memory retention — every agent turn calls CreateEvent
+        # to feed AgentCore's background strategies. Also needs read access
+        # so the recall() tool can fetch previously extracted records and
+        # so forget() can soft-archive old records.
+        Sid    = "AgentCoreMemoryReadWrite"
+        Effect = "Allow"
+        Action = [
+          "bedrock-agentcore:CreateEvent",
+          "bedrock-agentcore:ListEvents",
+          "bedrock-agentcore:GetEvent",
+          "bedrock-agentcore:ListMemoryRecords",
+          "bedrock-agentcore:RetrieveMemoryRecords",
+          "bedrock-agentcore:GetMemoryRecord",
+          "bedrock-agentcore:BatchCreateMemoryRecords",
+          "bedrock-agentcore:BatchUpdateMemoryRecords",
+        ]
+        Resource = "*"
+      },
       {
         Sid      = "CloudWatchLogs"
         Effect   = "Allow"
@@ -177,7 +190,6 @@ resource "aws_lambda_function" "agentcore" {
     variables = {
       PORT                   = "8080"
       AWS_LWA_PORT           = "8080"
-      MEMORY_ENGINE          = var.memory_engine
       AGENTCORE_MEMORY_ID    = var.agentcore_memory_id
       AGENTCORE_FILES_BUCKET = var.bucket_name
     }
@@ -193,10 +205,9 @@ resource "aws_lambda_function" "agentcore" {
   }
 }
 
-resource "aws_lambda_function_url" "agentcore" {
-  function_name      = aws_lambda_function.agentcore.function_name
-  authorization_type = "NONE"
-}
+# AgentCore is invoked directly via the Lambda SDK (InvokeCommand) from
+# chat-agent-invoke — no Function URL is needed, and exposing one would be
+# a public attack surface for prompt injection.
 
 ################################################################################
 # Outputs
@@ -212,12 +223,12 @@ output "execution_role_arn" {
   value       = aws_iam_role.agentcore.arn
 }
 
-output "agentcore_invoke_url" {
-  description = "Lambda Function URL for the AgentCore container"
-  value       = aws_lambda_function_url.agentcore.function_url
-}
-
 output "agentcore_function_name" {
   description = "AgentCore Lambda function name (for direct SDK invoke)"
   value       = aws_lambda_function.agentcore.function_name
 }
+
+output "agentcore_function_arn" {
+  description = "AgentCore Lambda function ARN (for IAM policy on callers)"
+  value       = aws_lambda_function.agentcore.arn
+}