# Class LittleGhost::Session

Documentation version: Edge

Canonical HTML: https://littleghostai.org/docs/LittleGhost/Session.html

Sessions let an agent continue a conversation without tying it to one Ruby
process. Each session keeps messages, application state, and metadata together
behind a SessionStore.

    session = LittleGhost::Session.new(
      id: "conversation-42",
      actor_id: "user-7",
      store: LittleGhost::SessionStores::Memory.new
    )
    session.append(
      messages: [LittleGhost::Message.new(role: :user, content: "Hello")],
      state: {language: "en"}
    )

    reopened = LittleGhost::Session.new(
      id: "conversation-42",
      actor_id: "user-7",
      store: session.store
    )
    reopened.history.last.text # => "Hello"
    reopened.state[:language]  # => "en"

### Persistence and trust

System messages, transient messages, and private model reasoning are removed
before persistence. Store failures reach the caller. A successful write
becomes the checkpoint used by later updates.

Multi-tenant applications must derive `actor_id` from stable, authenticated
identity. A nil actor provides no tenant isolation and is appropriate only for
a store that serves one actor.

## Inheritance

`LittleGhost::Session < Object`

## Attributes

<a id="attribute-i-actor_id"></a>
### `actor_id` (R)

The trusted application identity that owns this Session, when supplied.

<a id="attribute-i-id"></a>
### `id` (R)

The key used to load and save this Session.

<a id="attribute-i-operation_id"></a>
### `operation_id` (R)

The telemetry operation associated with this Session, when supplied.

<a id="attribute-i-store"></a>
### `store` (R)

The SessionStore that loads and saves snapshots.

## Class methods

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

```ruby
.new(id:, store:, actor_id: nil, metadata: {}, operation_id: nil)
```

No store access occurs until the session is read or written.

## Instance methods

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

```ruby
#append(messages:, state: self.state, metadata: self.metadata)
```

Atomically appends `messages` when the store still has the expected history
length. Prefer #checkpoint when replacing earlier messages is also valid.

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

```ruby
#checkpoint(messages:, state: self.state, metadata: self.metadata, parent_operation_id: @operation_id)
```

Persists one conversation checkpoint. History is appended when the stored
messages are an unchanged prefix and replaced otherwise.

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

```ruby
#checkpoint_result(result)
```

Checkpoints the messages and state from a completed run result.

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

```ruby
#history(fallback: [])
```

Uses persisted conversation messages when present and `fallback` for a new
session.

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

```ruby
#load()
```

Loads and normalizes the snapshot once. A new session has no snapshot.

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

```ruby
#metadata()
```

Uses persisted metadata when present and otherwise keeps the metadata from
construction. The returned DataMap is frozen.

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

```ruby
#project_conversation(messages:, metadata: self.metadata)
```

Publishes a conversational view without changing the session's stored
transcript. Unlike session persistence, projection does not automatically
remove system or transient messages; callers must omit any message whose
visible text should stay local. Stores that do not support projections return
nil.

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

```ruby
#replace(messages:, state: self.state, metadata: self.metadata)
```

Replaces the complete persisted snapshot.

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

```ruby
#state()
```

Exposes a mutable DataMap copy of the persisted application state. String and
Symbol keys address the same value; persisted snapshots use Strings.

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

```ruby
#synchronize(&block)
```

Serializes work for this session and actor through the backing store.