integrations/agentcore/v0.1.0

# Release Notes for memanto-agentcore v0.1.0

First release of **`memanto-agentcore`** durable memory for [Amazon Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock/latest/userguide/agentcore.html) handlers using Memanto. AgentCore sessions are ephemeral; Memanto keeps context in a stable namespace keyed by **tenant + user + agent**, not by `runtimeSessionId`. This package wraps each handler turn in **recall → execute → retain**, matching the Hindsight AgentCore pattern while using Memanto’s SDK and Moorcheh semantic search.

## New Features

- **Runtime adapter** (`memanto_agentcore/adapter.py`)
  - `MemantoRuntimeAdapter` with `before_turn()`, `after_turn()`, and `run_turn()` for a full handler loop.
  - `before_turn()` runs semantic recall and returns formatted prompt context for your Bedrock/agent call.
  - `after_turn()` stores the turn as a Memanto memory (default type `event`, tags `agentcore`, `turn`).
  - `retain_async=True` (default) retains in a background task so the handler response is not blocked.
- **Stable identity model**
  - `TurnContext` carries `runtime_session_id`, `user_id`, `agent_name`, optional `tenant_id` and `request_id`.
  - Default `agent_id` shape: `tenant-{tenant_id}-user-{user_id}-agent-{agent_name}` (sanitized to `[A-Za-z0-9_-]`).
  - Long ids hash a structured `\x1f`-separated tenant/user/agent key to a 64-char hex id (no ambiguous concatenation).
  - `resolve_agent_id()` rejects blank `user_id` before custom or default resolvers run (`AgentResolutionError`, fail closed).
- **Custom namespace**
  - Pass `agent_id_resolver=` to map `TurnContext` → Memanto `agent_id` (same role as a Hindsight memory bank id).
- **Fail-open recall, fail-quiet retain**
  - Recall errors log a warning and return `""` so the handler still runs.
  - Retain errors log a warning and do not affect the user-facing turn result.
- **Smoke validation**
  - `integrations/agentcore/scripts/smoke_test.py` — retain in session A, recall in session B (new `runtimeSessionId`), full `run_turn`, and cross-user isolation check.

## Improvements

- **Shared `SdkClient` session safety**
  - `_setup_lock` serializes bind + recall/remember on the same client.
  - `_ensure_session` re-activates when `client.agent_id` ≠ resolved `agent_id`, so switching users/agents in one adapter instance does not recall against the wrong session.
  - `_session_ready` tracks created agents; stale sessions are discarded and rebound on `SessionError` with one retry.
- **Public API surface** (`memanto_agentcore/__init__.py`)
  - Exports: `MemantoRuntimeAdapter`, `TurnContext`, `default_agent_id_resolver`, `AgentResolutionError`.

## Known Limits

- **Preview** — install from `integrations/agentcore` in the Memanto repo until PyPI publish; tag **`integrations/agentcore/v0.1.0`** for this release.
- **Not a Bedrock substitute** — you still deploy and invoke AgentCore Runtime; this adapter only adds Memanto I/O around your handler.
- **Identity is your responsibility** — `user_id` must come from validated JWT, AgentCore identity headers, or trusted server-side auth; never from client-supplied session ids alone.
- **Async retain** — with `retain_async=True`, process shutdown may drop an in-flight retain unless you await or flush; use `retain_async=False` in smoke tests and when you need synchronous persistence.
- **Indexing lag** — Moorcheh recall may lag a few seconds after retain; smoke script and live tests retry recall.

## Requirements

- Python **3.10+**
- **`memanto>=0.2.21`** (installed automatically with `memanto-agentcore`)
- **`MOORCHEH_API_KEY`** (or `~/.memanto/.env` via `memanto` CLI)
- AgentCore Runtime handler (async recommended for `run_turn` / `before_turn` / `after_turn`)
- AWS setup for AgentCore deploy/invoke is separate from Memanto

## Tests

- **7 unit tests** — agent id resolution, cross-session stability, `before_turn` formatting, recall failure → empty context, `run_turn` retain path, blank `user_id` rejection (`integrations/agentcore/tests/test_adapter.py`).
- **1 live test** — retain then recall across churned runtime session ids when `MOORCHEH_API_KEY` is set (`test_adapter_live.py`).
- From repo root: `python -m pytest integrations/agentcore/tests/test_adapter.py -q`
- Live smoke: `python integrations/agentcore/scripts/smoke_test.py`

## Full Changelog

Full Changelog: https://github.com/moorcheh-ai/memanto/commits/integrations/agentcore/v0.1.0