class LittleGhost::SessionStores::AgentCoreMemory

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.

Public Class Methods

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

Source

# File lib/little_ghost/session_stores/agent_core_memory.rb, line 104
def initialize(
  memory_id:,
  client: nil,
  client_factory: nil,
  region: nil,
  clock: -> { Time.now }
)
  super()
  @memory_id = String(memory_id)
  raise ArgumentError, "memory_id must not be empty" if @memory_id.empty?

  @region = region
  @client_factory = client_factory || -> { build_client(@region) }
  @client = client || @client_factory.call
  @clock = clock
  @operation_context_key = :"little_ghost_session_store_operation_#{object_id}"
  @client_mutex = Mutex.new
  @persistence_locks = {}
  @persistence_locks_mutex = Mutex.new
end

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

Calls superclass method LittleGhost::SessionStore::new

safe_id (value)

Source

# File lib/little_ghost/session_stores/agent_core_memory.rb, line 98
def self.safe_id(value)
  "lg_#{Digest::SHA256.hexdigest(String(value))}"
end

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

Public Instance Methods

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

Source

# File lib/little_ghost/session_stores/agent_core_memory.rb, line 143
def append(id, messages:, state:, metadata:, expected_count:, actor_id: nil)
  messages = persistable_messages(messages)
  state = DataMap.new(state).to_h
  metadata = DataMap.new(metadata).to_h
  actor = self.class.safe_id(required_actor_id(actor_id))
  session = self.class.safe_id(id)
  key = [actor, session]
  synchronize_persistence(key) do
    head, lineage = latest_checkpoint(actor, session)
    persistence = head&.fetch(:checkpoint)
    persisted_count = persistence&.fetch(:message_count, 0) || 0
    unless persisted_count == expected_count
      raise ProtocolError, "Session changed while it was being updated"
    end

    if head && head.fetch(:format) != CHECKPOINT_EVENT_TYPE
      existing = messages_from(message_records_for(actor, session, lineage:), lineage:)
      messages = [*existing, *messages].freeze
      expected_count = 0
      persistence = head.fetch(:checkpoint)
      root = true
      generation = SecureRandom.uuid
    else
      root = persistence.nil?
      generation = persistence&.fetch(:generation) || SecureRandom.uuid
    end
    commit_id = SecureRandom.uuid
    plan = plan_messages(messages, generation:, commit_id:, offset: expected_count)
    checkpoint = build_checkpoint(
      persistence:,
      generation:,
      commit_id:,
      root:,
      plan:,
      message_count: root ? messages.length : expected_count + messages.length,
      state:,
      metadata:
    )
    persist_commit(actor, session, plan:, checkpoint:, previous_timestamp: head&.fetch(:event_timestamp))
  end
  {messages:, state:, metadata:}
end

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

load (id, actor_id: nil)

Source

# File lib/little_ghost/session_stores/agent_core_memory.rb, line 126
def load(id, actor_id: nil)
  actor = self.class.safe_id(required_actor_id(actor_id))
  session = self.class.safe_id(id)
  head, lineage = latest_checkpoint(actor, session)
  return unless head

  checkpoint = head.fetch(:checkpoint)
  records = message_records_for(actor, session, lineage:)
  {
    messages: messages_from(records, lineage:),
    state: checkpoint.fetch(:state),
    metadata: checkpoint.fetch(:metadata)
  }
end

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

project_conversation (id, messages:, metadata:, actor_id: nil)

Source

# File lib/little_ghost/session_stores/agent_core_memory.rb, line 219
def project_conversation(id, messages:, metadata:, actor_id: nil)
  payload = persistable_messages(messages).filter_map do |message|
    text = message.text
    next if text.empty?

    conversational_payload(text, message.role)
  end
  return if payload.empty?

  event_metadata = {
    EVENT_TYPE_METADATA_KEY => {string_value: CONVERSATION_PROJECTION_EVENT_TYPE}
  }
  PROJECTION_METADATA_KEYS.each do |key|
    value = metadata[key] || metadata[key.to_sym]
    event_metadata[key] = {string_value: value.to_s} unless value.nil?
  end
  agent_core_call(
    :create_event,
    memory_id: @memory_id,
    actor_id: self.class.safe_id(required_actor_id(actor_id)),
    session_id: self.class.safe_id(id),
    event_timestamp: next_event_timestamp(nil),
    payload:,
    metadata: event_metadata,
    extraction_mode: "SKIP"
  )
end

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.

replace (id, messages:, state:, metadata:, actor_id: nil)

Source

# File lib/little_ghost/session_stores/agent_core_memory.rb, line 187
def replace(id, messages:, state:, metadata:, actor_id: nil)
  messages = persistable_messages(messages)
  state = DataMap.new(state).to_h
  metadata = DataMap.new(metadata).to_h
  actor = self.class.safe_id(required_actor_id(actor_id))
  session = self.class.safe_id(id)
  key = [actor, session]
  synchronize_persistence(key) do
    head, = latest_checkpoint(actor, session)
    persistence = head&.fetch(:checkpoint)
    generation = SecureRandom.uuid
    commit_id = SecureRandom.uuid
    plan = plan_messages(messages, generation:, commit_id:, offset: 0)
    checkpoint = build_checkpoint(
      persistence:,
      generation:,
      commit_id:,
      root: true,
      plan:,
      message_count: messages.length,
      state:,
      metadata:
    )
    persist_commit(actor, session, plan:, checkpoint:, previous_timestamp: head&.fetch(:event_timestamp))
  end
  {messages:, state:, metadata:}
end

Replaces the visible snapshot by committing a new remote generation.

with_operation_context (operation_id) { || ... }

Source

# File lib/little_ghost/session_stores/agent_core_memory.rb, line 248
def with_operation_context(operation_id)
  ExecutionState.with(@operation_context_key => operation_id) { yield }
end

Parents AgentCore telemetry emitted in the block to operation_id.