thinkwork-cli 0.5.2 → 0.5.3

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
+}

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

@@ -1,66 +1,87 @@
-# Memory Engine Module
+# Hindsight Memory Module (optional add-on)
 
-Thinkwork supports pluggable long-term memory for agents. Choose the engine that fits your stage and requirements.
+Thinkwork has two long-term memory systems. **AgentCore managed memory is
+always on** — every agent gets automatic per-turn retention out of the box
+with zero configuration. **Hindsight is an optional add-on** you can layer
+on top for advanced semantic + entity-graph retrieval.
 
-## Engines
+## Memory layers
 
-| Engine | `memory_engine` value | Best for | Extra infra | Cost |
-|--------|----------------------|----------|-------------|------|
-| **AgentCore Managed** | `managed` (default) | All stages. Production-ready, zero-config. | None | $0 additional |
-| **Hindsight** | `hindsight` | Advanced recall/reflect with entity graph, cross-encoder reranking. | ECS Fargate + ALB | ~$75/mo (ARM64) |
+| Layer | Backend | Always on | What it stores |
+|-------|---------|-----------|----------------|
+| 1. Workspace files | S3 per-agent | Yes | Scratchpad, working files |
+| 2. Thread history | Aurora `messages` table | Yes | Last 30 turns per thread |
+| 3a. Managed long-term | AgentCore Memory | **Yes** | Semantic facts, preferences, summaries, episodes — extracted automatically from every turn |
+| 3b. Hindsight long-term | Hindsight ECS service | **Optional** | Same purpose as 3a, plus entity graph + BM25 + cross-encoder reranking |
 
-Both engines provide agents with memory tools. The Strands runtime reads `MEMORY_ENGINE` and loads the right tool set:
+## How retention works
 
-- **Managed**: `remember()`, `recall()`, `forget()` — backed by AgentCore Memory API with 4 strategies (semantic facts, user preferences, session summaries, episodic).
-- **Hindsight**: `hindsight_retain()`, `hindsight_recall()`, `hindsight_reflect()` — backed by the Hindsight service with semantic + BM25 + entity graph + temporal retrieval and cross-encoder reranking.
+The agent container automatically emits a `CreateEvent` into AgentCore
+Memory after every turn (user message + assistant response), via
+`memory.store_turn_pair` in `packages/agentcore/agent-container/memory.py`.
+AgentCore's background strategies extract facts into four namespaces:
 
-## What's pluggable
+- `assistant_{actorId}` — semantic facts
+- `preferences_{actorId}` — user preferences
+- `session_{sessionId}` — session summaries
+- `episodes_{actorId}/{sessionId}` — episodic memory
 
-Only **Layer 3 (long-term cross-thread memory)** is pluggable. The other memory layers are core infrastructure:
+The agent reads them back via the `recall()` tool. There is no need for
+the model to call `remember()` for routine facts — it only exists for
+user-driven "please remember X" requests.
 
-- **Layer 1** — Workspace files on S3 (per-agent scratchpad). Always available.
-- **Layer 2** — Thread history in Aurora (conversation memory). Always available.
-- **Layer 3** — Long-term cross-thread recall. **This is what `memory_engine` controls.**
+When Hindsight is enabled, the container ALSO registers
+`hindsight_retain`, `hindsight_recall`, and `hindsight_reflect` tools that
+route to the Hindsight service. `remember()` dual-writes to both backends
+so explicit memories land in both systems.
 
 ## Usage
 
-### Managed (default — no extra config needed)
+### Default — managed memory only (zero config)
 
 ```hcl
 module "thinkwork" {
   source = "thinkwork-ai/thinkwork/aws"
 
-  stage      = "prod"
-  # memory_engine defaults to "managed" — nothing to set
+  stage = "prod"
+  # enable_hindsight defaults to false — nothing else to set
 }
 ```
 
-### Hindsight (opt-in)
+The `terraform/modules/app/agentcore-memory` module is always instantiated
+and provisions the AgentCore Memory resource with the four strategies.
+
+### With the Hindsight add-on
 
 ```hcl
 module "thinkwork" {
   source = "thinkwork-ai/thinkwork/aws"
 
-  stage         = "prod"
-  memory_engine = "hindsight"
+  stage            = "prod"
+  enable_hindsight = true
 
   # Optional: pin the Hindsight image version
-  # hindsight_image_tag = "0.4.22"
+  # hindsight_image_tag = "0.5.0"
 }
 ```
 
-When `memory_engine = "hindsight"`, Terraform creates:
+When `enable_hindsight = true`, Terraform creates:
 - ECS Fargate cluster + service (ARM64, 2 vCPU, 4 GB)
 - Application Load Balancer
 - Security groups (ALB → Hindsight → Aurora ingress)
 - CloudWatch log group
 
-When `memory_engine = "managed"`, none of the above is created.
+Cost: ~$75/mo (ARM64 Fargate + ALB hours).
+
+## Turning the add-on on/off
 
-## Switching engines
+Toggling `enable_hindsight` and re-running `thinkwork deploy`:
 
-Changing `memory_engine` and running `thinkwork deploy` will:
-- **managed → hindsight**: Create the ECS/ALB infrastructure. Agents start using Hindsight tools on next invoke.
-- **hindsight → managed**: Destroy the ECS/ALB infrastructure. Agents fall back to AgentCore memory tools.
+- **false → true**: creates the ECS + ALB infra. Agents gain the three
+  `hindsight_*` tools on their next invoke. Managed retention continues
+  running unchanged.
+- **true → false**: destroys the ECS + ALB infra. Agents lose the
+  `hindsight_*` tools. Managed memory keeps working as before.
 
-Memory data is not migrated between engines. Each engine has its own storage backend.
+Memory data is not migrated between backends. Hindsight records and
+AgentCore records live in separate stores.