agentcore-cli 0.31.1__py3-none-any.whl

agentcore/primitives/memory.py

@@ -0,0 +1,387 @@
+"""Memory add/remove (port of src/cli/primitives/MemoryPrimitive.tsx)."""
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+import typer
+from pydantic import ValidationError as PydanticValidationError
+
+from agentcore.cli import interactive
+from agentcore.cli.commands.add._common import first_issue
+from agentcore.cli.commands.add.validate import DEFAULT_DELIVERY_TYPE, validate_add_memory_options
+from agentcore.cli.commands.shared.arn_utils import ARN_VALIDATION_MESSAGE, is_valid_arn
+from agentcore.cli.commands.shared.indexed_key_parser import (
+    MAX_INDEXED_KEYS,
+    parse_indexed_key_arg,
+    validate_indexed_key_name,
+)
+from agentcore.cli.errors import get_error_message
+from agentcore.cli.naming import generate_unique_name
+from agentcore.cli.run_command import run_cli_command
+from agentcore.lib import ResourceNotFoundError, ValidationError, find_config_root, serialize_result
+from agentcore.lib.errors.types import to_error
+from agentcore.lib.result import Err, Ok
+from agentcore.lib.schemas.io.config_io import to_jsonable
+from agentcore.primitives.base import BasePrimitive, RemovableResource, RemovalPreview, SchemaChange, emit_json
+from agentcore.schema import (
+    DEFAULT_EPISODIC_REFLECTION_NAMESPACE_TEMPLATES,
+    DEFAULT_STRATEGY_NAMESPACE_TEMPLATES,
+    INDEXED_KEY_TYPES,
+    MEMORY_STRATEGY_TYPES,
+    STREAM_CONTENT_LEVELS,
+    AgentName,
+    StreamDeliveryResources,
+)
+
+DEFAULT_EVENT_EXPIRY = 30
+
+_STRATEGY_DESCRIPTIONS = {
+    "SEMANTIC": "Vector-based semantic search over memories",
+    "SUMMARIZATION": "Compress and summarize conversation context",
+    "USER_PREFERENCE": "Track and recall user preferences",
+    "EPISODIC": "Capture and reflect on meaningful interaction episodes",
+}
+EVENT_EXPIRY_OPTIONS = (
+    (7, "7 days", "Minimum retention"),
+    (30, "30 days", "One month"),
+    (90, "90 days", "Three months"),
+    (180, "180 days", "Six months"),
+    (365, "365 days", "Maximum retention"),
+)
+CONTENT_LEVEL_OPTIONS = (
+    ("FULL_CONTENT", "Full content", "Include memory record text in stream events"),
+    ("METADATA_ONLY", "Metadata only", "Only include metadata (IDs, timestamps, namespaces)"),
+)
+_INDEXED_KEY_TYPE_DESCRIPTIONS = {
+    "STRING": "Single string value",
+    "STRINGLIST": "List of string values",
+    "NUMBER": "Numeric value",
+}
+_LTM_STRATEGY_TYPES = ("SEMANTIC", "USER_PREFERENCE", "SUMMARIZATION", "EPISODIC")
+
+
+@dataclass
+class AddMemoryOptions:
+    name: str
+    strategies: str | None = None
+    expiry: int | None = None
+    delivery_type: str | None = None
+    data_stream_arn: str | None = None
+    content_level: str | None = None
+    stream_delivery_resources: str | None = None
+    indexed_key: list[str] | None = field(default=None)
+
+
+def _strategy(strategy_type: str) -> dict[str, Any]:
+    strategy: dict[str, Any] = {"type": strategy_type}
+    templates = DEFAULT_STRATEGY_NAMESPACE_TEMPLATES.get(strategy_type)  # type: ignore[call-overload]
+    if templates:
+        strategy["namespaceTemplates"] = list(templates)
+    if strategy_type == "EPISODIC":
+        strategy["reflectionNamespaceTemplates"] = list(DEFAULT_EPISODIC_REFLECTION_NAMESPACE_TEMPLATES)
+    return strategy
+
+
+class MemoryPrimitive(BasePrimitive):
+    kind = "memory"
+    label = "Memory"
+    article = "a"
+
+    def _project(self) -> dict[str, Any]:
+        return to_jsonable(self.read_project_spec())
+
+    def add(self, options: AddMemoryOptions) -> Ok[dict[str, Any]] | Err[Exception]:
+        try:
+            strategies: list[str] = []
+            if options.strategies:
+                for s in (s.strip() for s in options.strategies.split(",")):
+                    if not s:
+                        continue
+                    if s not in MEMORY_STRATEGY_TYPES:
+                        raise ValueError(f"Invalid option: expected one of {'|'.join(MEMORY_STRATEGY_TYPES)}")
+                    strategies.append(s)
+
+            stream_delivery_resources = None
+            if options.stream_delivery_resources:
+                stream_delivery_resources = self._parse_stream_delivery_resources(options.stream_delivery_resources)
+            elif options.data_stream_arn:
+                level = options.content_level or "FULL_CONTENT"
+                if level not in STREAM_CONTENT_LEVELS:
+                    raise ValueError(f"Invalid option: expected one of {'|'.join(STREAM_CONTENT_LEVELS)}")
+                stream_delivery_resources = self._build_stream_delivery_resources(
+                    options.delivery_type or DEFAULT_DELIVERY_TYPE, options.data_stream_arn, level
+                )
+
+            indexed_keys = self._parse_indexed_keys(options.indexed_key) if options.indexed_key else None
+
+            project = self._project()
+            self.check_duplicate([RemovableResource(m["name"]) for m in project["memories"]], options.name)
+            memory: dict[str, Any] = {
+                "name": options.name,
+                "eventExpiryDuration": options.expiry if options.expiry is not None else DEFAULT_EVENT_EXPIRY,
+                "strategies": [_strategy(s) for s in strategies],
+            }
+            if indexed_keys:
+                memory["indexedKeys"] = indexed_keys
+            if stream_delivery_resources:
+                memory["streamDeliveryResources"] = stream_delivery_resources
+            project["memories"].append(memory)
+            self.write_project_spec(project)
+            return Ok({"memoryName": memory["name"]})
+        except Exception as exc:  # noqa: BLE001
+            return Err(to_error(exc))
+
+    @staticmethod
+    def _build_stream_delivery_resources(delivery_type: str, data_stream_arn: str, level: str) -> dict[str, Any]:
+        if delivery_type == DEFAULT_DELIVERY_TYPE:
+            return {
+                "resources": [
+                    {
+                        "kinesis": {
+                            "dataStreamArn": data_stream_arn,
+                            "contentConfigurations": [{"type": "MEMORY_RECORDS", "level": level}],
+                        }
+                    }
+                ]
+            }
+        raise Exception(f"Unsupported delivery type: {delivery_type}")
+
+    @staticmethod
+    def _parse_stream_delivery_resources(text: str) -> dict[str, Any]:
+        try:
+            data = json.loads(text)
+        except ValueError:
+            raise Exception("Invalid JSON in stream delivery config") from None
+        try:
+            return StreamDeliveryResources.model_validate(data).model_dump(mode="json", by_alias=True)
+        except PydanticValidationError as exc:
+            detail = ", ".join(e["msg"] for e in exc.errors())
+            raise Exception(f"Stream delivery config does not match the expected schema: {detail}") from None
+
+    @staticmethod
+    def _parse_indexed_keys(raw_keys: list[str]) -> list[dict[str, Any]]:
+        keys = []
+        for raw in raw_keys:
+            parsed = parse_indexed_key_arg(raw)
+            if not parsed.ok:
+                raise Exception(parsed.error)
+            keys.append(parsed.value)
+        return keys  # type: ignore[return-value]
+
+    def remove(self, name: str) -> Ok[None] | Err[Exception]:
+        try:
+            project = self._project()
+            index = next((i for i, m in enumerate(project["memories"]) if m["name"] == name), -1)
+            if index == -1:
+                return Err(ResourceNotFoundError(f'Memory "{name}" not found.'))
+            project["memories"].pop(index)
+            self.write_project_spec(project)
+            return Ok(None)
+        except Exception as exc:  # noqa: BLE001
+            return Err(to_error(exc))
+
+    def preview_remove(self, name: str) -> RemovalPreview:
+        project = self._project()
+        if not any(m["name"] == name for m in project["memories"]):
+            raise Exception(f'Memory "{name}" not found.')
+        after = {**project, "memories": [m for m in project["memories"] if m["name"] != name]}
+        return RemovalPreview(
+            [f"Removing memory: {name}"], [], [SchemaChange("agentcore/agentcore.json", project, after)]
+        )
+
+    def get_removable(self) -> list[RemovableResource]:
+        try:
+            return [RemovableResource(m["name"]) for m in self._project()["memories"]]
+        except Exception:  # noqa: BLE001
+            return []
+
+    def get_all_names(self) -> list[str]:
+        return [r.name for r in self.get_removable()]
+
+    # --- CLI ----------------------------------------------------------------------------
+
+    def register_commands(self, add_app: typer.Typer, remove_app: typer.Typer) -> None:
+        @add_app.command("memory", help="Add a memory to the project")
+        def add_memory(
+            name: str | None = typer.Option(None, "--name", help="Memory name [non-interactive]"),
+            strategies: str | None = typer.Option(
+                None,
+                "--strategies",
+                help="Comma-separated strategies: SEMANTIC, SUMMARIZATION, USER_PREFERENCE, EPISODIC [non-interactive]",
+            ),
+            expiry: str | None = typer.Option(
+                None, "--expiry", help="Event expiry duration in days (default: 30) [non-interactive]"
+            ),
+            delivery_type: str | None = typer.Option(
+                None, "--delivery-type", help="Delivery target type (default: kinesis) [non-interactive]"
+            ),
+            data_stream_arn: str | None = typer.Option(
+                None,
+                "--data-stream-arn",
+                help="Kinesis data stream ARN for memory record streaming [non-interactive]",
+            ),
+            stream_content_level: str | None = typer.Option(
+                None,
+                "--stream-content-level",
+                help="Stream content level: FULL_CONTENT or METADATA_ONLY (default: FULL_CONTENT) [non-interactive]",
+            ),
+            stream_delivery_resources: str | None = typer.Option(
+                None,
+                "--stream-delivery-resources",
+                help="Stream delivery config as JSON string (advanced, overrides flat flags) [non-interactive]",
+            ),
+            indexed_key: list[str] = typer.Option(
+                [],
+                "--indexed-key",
+                help="Indexed metadata key as key:TYPE (repeatable, max 10). TYPE is STRING, STRINGLIST, or NUMBER "
+                "[non-interactive]",
+            ),
+            as_json: bool = typer.Option(False, "--json", help="Output as JSON [non-interactive]"),
+        ) -> None:
+            if not find_config_root():
+                typer.echo("No agentcore project found. Run `agentcore create` first.", err=True)
+                raise typer.Exit(1)
+
+            if not (name or as_json):
+                try:
+                    interactive.require_tty()
+                    self.add_interactive()
+                except typer.Exit:
+                    raise
+                except Exception as exc:  # noqa: BLE001
+                    typer.echo(get_error_message(exc), err=True)
+                    raise typer.Exit(1) from None
+                raise typer.Exit(0)
+
+            def run() -> None:
+                expiry_days = _parse_int(expiry) if expiry else None
+                keys = list(indexed_key) or None
+                validation = validate_add_memory_options(
+                    {
+                        "name": name,
+                        "strategies": strategies,
+                        "expiry": expiry_days,
+                        "deliveryType": delivery_type,
+                        "dataStreamArn": data_stream_arn,
+                        "contentLevel": stream_content_level,
+                        "streamDeliveryResources": stream_delivery_resources,
+                        "indexedKey": keys,
+                    }
+                )
+                if not validation.valid:
+                    raise ValidationError(validation.error or "")
+                result = self.add(
+                    AddMemoryOptions(
+                        name=name or "",
+                        strategies=strategies,
+                        expiry=expiry_days,
+                        delivery_type=delivery_type,
+                        data_stream_arn=data_stream_arn,
+                        content_level=stream_content_level,
+                        stream_delivery_resources=stream_delivery_resources,
+                        indexed_key=keys,
+                    )
+                )
+                if not result.success:
+                    raise result.error
+                if as_json:
+                    emit_json(serialize_result(result))
+                else:
+                    typer.echo(f"Added memory '{result.value['memoryName']}'")
+
+            run_cli_command(as_json, run)
+
+        self.register_remove_subcommand(remove_app)
+
+    def add_interactive(self) -> None:
+        """Prompt flow mirroring tui/screens/memory/AddMemoryScreen."""
+        existing = self.get_all_names()
+
+        def validate_name(value: str) -> str | None:
+            return first_issue(AgentName, value) or ("Memory name already exists" if value in existing else None)
+
+        name = interactive.text(
+            "Memory name", default=generate_unique_name("MyMemory", existing), validate=validate_name
+        )
+        expiry = interactive.select(
+            "Event expiry duration",
+            [interactive.Choice(t, v, d) for v, t, d in EVENT_EXPIRY_OPTIONS],
+            default=None,
+        )
+        strategies = interactive.checkbox(
+            "Select memory strategies",
+            [
+                interactive.Choice(s[0] + s[1:].lower().replace("_", " "), s, _STRATEGY_DESCRIPTIONS.get(s))
+                for s in MEMORY_STRATEGY_TYPES
+            ],
+        )
+
+        indexed_keys: list[str] = []
+        if any(s in _LTM_STRATEGY_TYPES for s in strategies) and interactive.confirm(
+            "Define indexed metadata keys?", default=False
+        ):
+            names: list[str] = []
+            while True:
+                key = interactive.text(
+                    "Metadata key name",
+                    validate=lambda v: (lambda r: None if r is True else r)(validate_indexed_key_name(v, names)),
+                )
+                key_type = interactive.select(
+                    f'Select type for "{key}"',
+                    [interactive.Choice(t, t, _INDEXED_KEY_TYPE_DESCRIPTIONS[t]) for t in INDEXED_KEY_TYPES],
+                )
+                names.append(key)
+                indexed_keys.append(f"{key}:{key_type}")
+                if len(names) >= MAX_INDEXED_KEYS or not interactive.confirm(
+                    f"Add another indexed key? ({len(names)} of {MAX_INDEXED_KEYS} maximum keys defined)",
+                    default=False,
+                ):
+                    break
+
+        data_stream_arn = content_level = None
+        if interactive.confirm("Enable memory record streaming?", default=False):
+            data_stream_arn = interactive.text(
+                "Delivery target ARN (e.g. Kinesis stream)",
+                validate=lambda v: None if is_valid_arn(v) else ARN_VALIDATION_MESSAGE,
+            )
+            content_level = interactive.select(
+                "Stream content level", [interactive.Choice(t, v, d) for v, t, d in CONTENT_LEVEL_OPTIONS]
+            )
+
+        typer.echo(f"  Name: {name}")
+        typer.echo(f"  Expiry: {expiry} days")
+        typer.echo(f"  Strategies: {', '.join(strategies) if strategies else 'None'}")
+        if indexed_keys:
+            typer.echo(f"  Indexed Keys: {', '.join(indexed_keys)}")
+        if data_stream_arn:
+            typer.echo(f"  Stream ARN: {data_stream_arn}")
+            typer.echo(f"  Content Level: {content_level}")
+        if not interactive.confirm("Add this memory?", default=True):
+            typer.echo("Cancelled.")
+            return
+        result = self.add(
+            AddMemoryOptions(
+                name=name,
+                expiry=expiry,
+                strategies=",".join(strategies) or None,
+                data_stream_arn=data_stream_arn,
+                content_level=content_level,
+                indexed_key=indexed_keys or None,
+            )
+        )
+        if not result.success:
+            typer.echo(get_error_message(result.error), err=True)
+            raise typer.Exit(1)
+        typer.echo(f"Added memory: {name}")
+
+
+def _parse_int(value: str) -> int | None:
+    """parseInt(value, 10): leading integer digits, else NaN (None)."""
+    import re
+
+    m = re.match(r"^\s*([+-]?\d+)", value)
+    return int(m.group(1)) if m else None
+
+
+PRIMITIVE = MemoryPrimitive()