Sessions archive rfd

[Rizzen]

---

title: "Session Archive and Unarchive"

Authors: Mark Tkachenko (@Rizzen), Evgeniy Stepanov(@xtmq)

Elevator pitch

What are you proposing to change?

Standardize reversible session archiving: Clients can hide conversations from default history, discover archived sessions, and restore them with the same ID and saved history.

Status quo

How do things work today and what problems does this cause? Why would we change things?

session/delete removes sessions from history but permits permanent deletion. session/close releases execution resources. Neither guarantees reversible hiding, and session/list cannot explicitly request archived sessions.

What we propose to do about it

What are you proposing to improve the situation?

Methods

session/archive hides a session from default history:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/archive",
  "params": { "sessionId": "sess_abc123" }
}

session/unarchive restores it:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/unarchive",
  "params": { "sessionId": "sess_abc123" }
}

Both return an empty result with the matching request ID:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}

sessionId is required and non-null. Both methods support the usual optional _meta field in requests and responses.

Capabilities

Agents advertise the methods independently:

• v1: agentCapabilities.sessionCapabilities.archive and .unarchive.
• v2 draft: capabilities.session.archive and .unarchive.

{} enables the corresponding method; omission or null means unsupported. Clients MUST check support before calling it.

Advertising either capability MUST also enable archived listing and state reporting. In v1, this requires sessionCapabilities.list: {}; v2 already requires listing for Agents supporting sessions.

Example v1 initialization response:

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "sessionCapabilities": {
        "list": {},
        "archive": {},
        "unarchive": {}
      }
    }
  }
}

Listing and state

Extend session/list with an optional archived parameter to include archived sessions:

Value	Sessions returned
Omitted, null, or false	Unarchived only.
true	Unarchived and archived.

Clients MUST NOT send this parameter without either archive capability. It combines with cwd and applies before pagination. Clients keep the same cwd and archived values when following nextCursor; changing either starts a new pagination sequence.

Include archived sessions alongside unarchived sessions:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "session/list",
  "params": {
    "cwd": "/home/user/project",
    "archived": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "sessions": [
      {
        "sessionId": "sess_abc123",
        "cwd": "/home/user/project",
        "title": "Implement session archive support",
        "archived": true
      },
      {
        "sessionId": "sess_def456",
        "cwd": "/home/user/project",
        "title": "Update session documentation",
        "archived": false
      }
    ]
  }
}

Add an optional, non-null boolean archived to:

• SessionInfo: required in list results when either archive capability is advertised. Otherwise, omission conveys no archive-state guarantee.
• SessionInfoUpdate: omission leaves state unchanged. Agents SHOULD report changes through existing session_info_update notifications to connected session observers. Listing remains the source of truth after reconnecting; no global subscription is introduced.

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123",
    "update": {
      "sessionUpdate": "session_info_update",
      "archived": true
    }
  }
}

Guarantees

• Preservation: Both operations preserve the ID and saved conversation. Archive state persists with session history across connections and restarts; ordinary retention policies still apply.
• Independent execution: Neither operation loads, resumes, closes, or cancels a session. Agents MAY reject archiving an active session without changing archive state if stopping it would be necessary. Clients can explicitly close it first.
• Explicit restoration: Closing, loading, or resuming does not change archive state. Agents may require unarchiving before loading or resuming.
• Idempotency: Repeating the desired state succeeds for retained, non-deleted sessions. Unknown, deleted, or expired sessions return Resource not found (-32002). Neither method requires activation on the current connection.
• Consistency: Success commits the change; subsequent list requests reflect it unless another operation intervenes. Concurrent mutations are serialized per session.
• Deletion: Deleted sessions remain excluded regardless of the archived parameter. Unarchive does not undo deletion; Clients must not substitute deletion for archiving.
• Activity: Archiving and unarchiving alone SHOULD NOT change updatedAt.

Shiny future

How will things will play out once this feature exists?

A user archives a conversation in one Client, finds it in another Client's archived history, and restores it for continued work.

Implementation details and plan

Tell me more about your implementation. What is your detailed implementation plan?

Add the methods, capabilities, filter, and state fields behind unstable_session_archive; regenerate v1/v2 schemas and update conversions, SDKs, and docs. Validate restoration, retries, persistence, pagination, active sessions, and deletion compatibility with Agent and Client implementations before preview.

Frequently asked questions

What questions have arisen over the course of authoring this document or during subsequent discussions?

Why separate methods?

They match the requested actions and allow independent capabilities. A boolean setter is possible, but a general metadata-editing API exceeds this request. Extending deletion cannot guarantee recovery when Agents may permanently remove data.

What needs discussion?

• Active sessions: Keep execution separate as proposed, or make archiving also close the session?
• Discovery: Should including archived sessions have its own capability for Agents that support neither mutation?
• Migration: Some adapters implement deletion through native archiving. They need a distinction to keep deleted sessions out of archived results; how should historical records without that distinction be handled?

Revision history

• 2026-09-14: Initial proposal.