Session Archive and Unarchive

• Author(s): @Rizzen, @xtmq
• Champion: @benbrandt

​

Elevator pitch

What are you proposing to change?

​

Status quo

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

​

What we propose to do about it

What are you proposing to improve the situation?

​

Methods

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

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

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

​

Capabilities

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

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

​

Listing and state

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

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

{
  "jsonrpc": "2.0",
  "id": 4,
  "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
      }
    ]
  }
}

• SessionInfo: Omission and null are equivalent and convey no archive-state guarantee. Agents that advertise archive MUST include a boolean value on every listed session.
• SessionInfoUpdate: Omission and null are equivalent and leave the archive state unchanged. Unlike title, null does not clear anything, because every session is either archived or not. Agents SHOULD report changes through existing session_info_update notifications to Clients that have the session open. 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
    }
  }
}

​

Semantics

• Preservation: Both operations preserve the ID and saved conversation. Archive state persists with session history across connections and restarts; ordinary retention policies still apply.
• Archiving closes active sessions: If the session is active, session/archive MUST cancel any ongoing work and free the session’s resources as if session/close had been called, then archive it. This does not require the close capability. Agents SHOULD send the archived: true session_info_update to Clients with the session open before closing it. session/unarchive never loads or resumes a session.
• Loading archived sessions: Closing, loading, or resuming does not change archive state. Agents MAY reject session/load or session/resume for an archived session. Clients that want to continue an archived session SHOULD call session/unarchive first; they already know the state from SessionInfo.archived.
• Idempotency: Archiving an archived session, or unarchiving an unarchived session, succeeds. Neither method requires the session to be active on the current connection.
• Unknown sessions: Unknown, deleted, or expired sessions return Resource not found (-32002). This differs from session/delete, which succeeds silently for unknown sessions because its end state (“not listed”) already holds. Neither archive state can hold for a session that doesn’t exist, so silently succeeding would hide stale or mistyped IDs.
• Consistency: Success commits the change; subsequent list requests reflect it unless another operation intervenes.
• Deletion: Deleted sessions are excluded from every archived filter value, and unarchiving does not restore a deleted session. Agents that advertise archive MUST NOT implement session/delete as an archive that later shows up in archived listings.
• Subagent sessions: Archiving applies to the given session. Whether archiving a parent also archives its subagent sessions is implementation-defined; some Agents archive the whole tree.

​

Shiny future

How will things will play out once this feature exists?

​

Implementation details and plan

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

​

Frequently asked questions

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

​

Why separate methods?

​

Why does archiving close an active session?

​

Why a three-value list filter instead of a boolean?

​

What alternative approaches did you consider, and why did you settle on this one?

• Extend session/delete with soft-delete semantics: Deletion may be permanent and its behavior is implementation-defined, so it cannot guarantee recovery.
• A single session/setArchived method with a boolean: Equivalent in power, but two methods match the rest of the session lifecycle methods and keep each request’s intent obvious.
• A general session-metadata editing method: Larger in scope than this proposal needs.

​

What needs discussion?

• Discovery: Should listing archived sessions have its own capability for Agents that support neither mutation?

​

Revision history

• 2026-10-28: Archiving closes active sessions; three-value archived list filter; clarified null handling, errors, deletion, and subagent sessions; removed the updatedAt requirement.
• 2026-09-14: Initial proposal.