# Class LittleGhost::SessionStores::AgentCoreMemory

Documentation version: Edge

Canonical HTML: https://littleghostai.org/docs/LittleGhost/SessionStores/AgentCoreMemory.html

AgentCoreMemory keeps LittleGhost conversations in Amazon Bedrock AgentCore
Memory so they can resume across Ruby processes and deployments.

    store = LittleGhost::SessionStores::AgentCoreMemory.new(
      memory_id: ENV.fetch("AGENTCORE_MEMORY_ID"),
      region: "us-east-1"
    )

Configure the resulting store through Configuration#session_store; a Runtime
then owns its construction and lifetime. The optional
`aws-sdk-bedrockagentcore` dependency is loaded only when a client
is not supplied.

### Privacy and concurrency

This store sends session data to Amazon Bedrock AgentCore Memory. For stored
transcripts and checkpoints, Session removes system messages, transient
messages, and private reasoning first. The remaining complete message records
may still contain personal data, visible text, attachments, tool calls and
results, and message metadata. Checkpoints also send application state and
session metadata.

Conversation projection is a separate path. It removes private reasoning, but
sends visible text from every message the caller supplies, including system or
transient messages. Callers must filter projection input when those messages
should stay local. Projection also sends selected metadata. None of this
filtering anonymizes the remaining content.

Use a memory, region, IAM policy, retention policy, and logging policy
approved for that data. Do not enable this store for content that is not
approved to leave the Ruby process.

Session and actor identifiers become deterministic SHA-256 pseudonyms before
leaving the process. These values remain linkable, and low-entropy identifiers
may be recovered by dictionary matching. Treat them as sensitive identifiers,
not anonymous data.

AgentCore's immutable event API requires one active writer for each
actor/session pair. This store serializes writers inside one Ruby process, but
horizontally scaled applications need an external lock or unique active-run
record. Commits use generation and checkpoint records so an incomplete write
is never exposed as a successful snapshot.

AgentCore checkpoints are versioned. This store reads supported historical
versions without writing during #load, then writes the current checkpoint
format when the session next appends or replaces its snapshot.

## Inheritance

`LittleGhost::SessionStores::AgentCoreMemory < LittleGhost::SessionStore`

## Class methods

<a id="method-c-new"></a>
### `.new`

```ruby
.new(memory_id:,
        client: nil,
        client_factory: nil,
        region: nil,
        clock: -> { Time.now })
```

Supply `client` for explicit dependency injection, or `region` and an optional
`client_factory` for lazy refresh.

<a id="method-c-safe_id"></a>
### `.safe_id`

```ruby
.safe_id(value)
```

Produces a stable AgentCore-safe pseudonym. This is not anonymization.

## Instance methods

<a id="method-i-append"></a>
### `#append`

```ruby
#append(id, messages:, state:, metadata:, expected_count:, actor_id: nil)
```

Appends sanitized messages as a new committed checkpoint when `expected_count`
matches the latest remote generation.

<a id="method-i-load"></a>
### `#load`

```ruby
#load(id, actor_id: nil)
```

Loads the latest committed generation for the required actor and session.

<a id="method-i-project_conversation"></a>
### `#project_conversation`

```ruby
#project_conversation(id, messages:, metadata:, actor_id: nil)
```

Writes visible conversational text for AgentCore Memory extraction without
changing LittleGhost's stored session transcript. This removes private
reasoning, but does not remove system or transient messages; callers must omit
any message whose visible text should stay local.

<a id="method-i-replace"></a>
### `#replace`

```ruby
#replace(id, messages:, state:, metadata:, actor_id: nil)
```

Replaces the visible snapshot by committing a new remote generation.

<a id="method-i-with_operation_context"></a>
### `#with_operation_context`

```ruby
#with_operation_context(operation_id)
```

Parents AgentCore telemetry emitted in the block to `operation_id`.