Feature Request: Add Built-in Session Persistence and Message History

[antonbrams]

Feature Request: Session Persistence and Message History Management
Problem Statement
The current @opencode-ai/sdk lacks built-in support for:

1. Session persistence (saving/restoring sessions)
2. Message history access (retrieving past messages in a session)
3. Context management (maintaining conversation state)
   This forces developers to implement custom persistence logic (e.g., JSON file storage), which is error-prone and inefficient. Session data (including message history) is lost when the server restarts, breaking conversation continuity.

---

Use Case
As a developer building a Telegram bot with @opencode-ai/sdk, I need to:

• Save conversations so users can resume them later.
• Restore session state when the server restarts.
• Access message history to provide context to the LLM.
  Currently, I must manually:

1. Track messages in a Map or JSON files.
2. Replay messages to the LLM to restore context.
3. Handle race conditions and duplicate messages.
   This adds unnecessary complexity and reduces reliability.

---

Proposed Solution
Add the following features to the SDK:

1. Session Persistence API

// Save a session (including messages)
await client.session.save(sessionId, { path: './sessions' });
// Load a session (restores messages and state)
const session = await client.session.load(sessionId, { path: './sessions' });

2. Message History Access

// Get all messages in a session
const messages = await client.message.list({ sessionId });
// Get a specific message
const message = await client.message.get({ sessionId, messageId });

3. Context Restoration

// Automatically restore session context on creation
const session = await client.session.create({
  id: 'my-session',
  restore: true, // Loads existing session if available
});

---

Benefits
✅ Simplified Development: No need for custom persistence logic.
✅ Reliability: Sessions survive server restarts.
✅ Context Awareness: LLMs retain conversation history.
✅ Performance: Reduces redundant message replay.

Alternatives Considered

1. Custom File Storage (current workaround):
   • Requires manual implementation.
   • Prone to race conditions and data loss.
2. Database Integration:
   • Adds external dependencies (e.g., SQLite, Redis).
   • Overkill for simple use cases.

---

Example Implementation
Here’s how the SDK could implement this (pseudo-code):

// Save session
async function save(sessionId, options) {
  const session = await this.get(sessionId);
  const messages = await this.message.list({ sessionId });
  const data = { ...session, messages };
  fs.writeFileSync(`${options.path}/session_${sessionId}.json`, JSON.stringify(data));
}
// Load session
async function load(sessionId, options) {
  const data = JSON.parse(fs.readFileSync(`${options.path}/session_${sessionId}.json`));
  const session = await this.create({ id: sessionId, ...data });
  for (const msg of data.messages) {
    if (msg.role === 'user') {
      await this.promptAsync({ sessionId, parts: [{ type: 'text', text: msg.content }] });
    }
  }
  return session;
}

---

Impact

• Minimal Breaking Changes: New methods are additive.
• Backward Compatibility: Existing code continues to work.
• Developer Experience: Simplifies building stateful applications (e.g., chatbots).