AgentCore Operator Wiring (Plan 3 of 3)

README.md

@@ -27,6 +27,19 @@ It's a memory layer for Claude Code that runs entirely on your machine. Your obs
 
 SQLite ships with Python; `sqlite-vec` is installed as a pip dependency — nothing else to set up.
 
+## Storage backends
+
+better-memory has two storage backends. Pick one:
+
+| Backend | When to pick | Setup |
+|---|---|---|
+| **`sqlite`** (default) | Single-machine usage; full offline operation; no cloud cost. | None — works out of the box. |
+| **`agentcore`** | Multi-machine syncing; managed extraction by AWS; team-shared memory bucket. | Requires AWS account with Bedrock AgentCore Memory enabled in `eu-west-2`. See [AgentCore setup](website/agentcore-setup.md). |
+
+Switch backends via `BETTER_MEMORY_STORAGE_BACKEND=agentcore` (default: `sqlite`). The MCP server reads the env var at startup and dispatches accordingly. Switching is one-way today — there is no bulk migration tool (deferred; clean start in agentcore mode is the supported path).
+
+`agentcore` mode needs the optional dependency group: `pip install 'better-memory[agentcore]'` (or `uv pip install '.[agentcore]'`). Sqlite-only installs skip boto3 entirely.
+
 ## Quick start
 
 ```bash

better_memory/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI subcommands for better-memory."""
+
+from better_memory.cli.main import main
+
+__all__ = ["main"]

better_memory/cli/_agentcore_strategies.py

@@ -0,0 +1,103 @@
+"""Memory-strategy definitions used by `agentcore init` and the smoke script.
+
+Lifted from `scripts/agentcore_smoke.py` so the CLI and the smoke share a
+single source of truth — diverging the two has bitten us before.
+"""
+
+from __future__ import annotations
+
+# Episodic memory: extracts reflections from session events. Metadata schema
+# carries the rating counters + polarity classification.
+EPISODIC_METADATA_SCHEMA: list[dict] = [
+    {
+        "key": "polarity",
+        "type": "STRING",
+        "extractionConfig": {
+            "llmExtractionConfig": {
+                "definition": (
+                    "Whether this reflection prescribes a positive practice "
+                    "('do'), warns against a negative practice ('dont'), or "
+                    "is informational only ('neutral')."
+                ),
+                "llmExtractionInstruction": (
+                    "Classify this reflection as 'do', 'dont', or 'neutral'."
+                ),
+                "validation": {
+                    "stringValidation": {
+                        "allowedValues": ["do", "dont", "neutral"]
+                    }
+                },
+            }
+        },
+    },
+    {"key": "useful_count", "type": "NUMBER"},
+    {"key": "missed_count", "type": "NUMBER"},
+    {"key": "ignored_count", "type": "NUMBER"},
+    {"key": "times_misled", "type": "NUMBER"},
+    {"key": "overlooked_count", "type": "NUMBER"},
+    {"key": "last_credited_at", "type": "STRING"},
+    {"key": "status", "type": "STRING"},
+]
+
+SEMANTIC_METADATA_SCHEMA: list[dict] = [
+    {"key": "useful_count", "type": "NUMBER"},
+    {"key": "missed_count", "type": "NUMBER"},
+    {"key": "ignored_count", "type": "NUMBER"},
+    {"key": "times_misled", "type": "NUMBER"},
+    {"key": "overlooked_count", "type": "NUMBER"},
+    {"key": "last_credited_at", "type": "STRING"},
+    {"key": "status", "type": "STRING"},
+]
+
+INDEXED_KEYS: list[dict] = [
+    {"key": "status", "type": "STRING"},
+    {"key": "last_credited_at", "type": "STRING"},
+    {"key": "overlooked_count", "type": "NUMBER"},
+]
+
+# Names — must match the AWS regex `[a-zA-Z][a-zA-Z0-9_]{0,47}` (no dashes!).
+DEFAULT_EPISODIC_NAME = "better_memory_episodic"
+DEFAULT_SEMANTIC_NAME = "better_memory_semantic"
+DEFAULT_EPISODIC_STRATEGY_NAME = "episodicReflections"
+DEFAULT_SEMANTIC_STRATEGY_NAME = "userPreference"
+
+# Event TTL: episodic events are kept ~90 days (long enough to span a multi-
+# month project); semantic records last ~365 days.
+DEFAULT_EPISODIC_EVENT_EXPIRY_DAYS = 90
+DEFAULT_SEMANTIC_EVENT_EXPIRY_DAYS = 365
+
+
+def episodic_strategy_block(
+    *,
+    name: str = DEFAULT_EPISODIC_STRATEGY_NAME,
+) -> dict:
+    return {
+        "episodicMemoryStrategy": {
+            "name": name,
+            "namespaces": ["projects/{actorId}/reflections/"],
+            "namespaceTemplates": ["projects/{actorId}/reflections/"],
+            "reflectionConfiguration": {
+                "namespaces": ["projects/{actorId}/reflections/"],
+                "namespaceTemplates": ["projects/{actorId}/reflections/"],
+                "memoryRecordSchema": {
+                    "metadataSchema": EPISODIC_METADATA_SCHEMA
+                },
+            },
+        }
+    }
+
+
+def semantic_strategy_block(
+    *,
+    name: str = DEFAULT_SEMANTIC_STRATEGY_NAME,
+) -> dict:
+    return {
+        "userPreferenceMemoryStrategy": {
+            "name": name,
+            "namespaces": ["projects/{actorId}/semantic/"],
+            "namespaceTemplates": ["projects/{actorId}/semantic/"],
+            "memoryRecordSchema": {
+                "metadataSchema": SEMANTIC_METADATA_SCHEMA
+            },
+        }
+    }