# Research: OpenCode Session Access (Memory Skill)

## Question

How to access historical OpenCode session data (conversations, plans, projects) for import into the hub's Postgres storage? The opencode-memory skill provides read-only SQLite access to local OpenCode data.

## Overview

The [opencode-memory skill](https://github.com/carson2222/skills) by carson2222 provides lightweight, read-only access to OpenCode's local history. It teaches agents how to query the OpenCode SQLite database directly using `sqlite3` CLI, covering sessions, messages, plans, and projects.

## Key Findings

### Storage Location

```
Database:       ${XDG_DATA_HOME:-$HOME/.local/share}/opencode/opencode.db
Plans:          ${XDG_DATA_HOME:-$HOME/.local/share}/opencode/plans/*.md
Session diffs:  ${XDG_DATA_HOME:-$HOME/.local/share}/opencode/storage/session_diff/<session-id>.json
Prompt history: ${XDG_STATE_HOME:-$HOME/.local/state}/opencode/prompt-history.jsonl
```

### Core Schema (What We Need)

- **project** — `id` (text PK), `worktree` (path), `name` (often NULL)
- **session** — `id` (text), `project_id` (FK), `parent_id` (for sub-sessions), `title`, `summary`, `time_created`, `time_updated`
- **message** — `id`, `session_id` (FK), `data` (JSON with role, agent, model, etc.), `time_created`
- **part** — `id`, `message_id` (FK), `session_id` (FK), `data` (JSON with type, text, etc.), `time_created`

This maps directly to our `projects`, `sessions`, `messages`, `parts` tables. See [../architecture/storage/sessions.md](../architecture/storage/sessions.md) for the mapping details.

### Agent/Role Fields

OpenCode stores an `agent` field on both `user` and `assistant` message data:
- On `user` messages: which agent the user selected for that turn
- On `assistant` messages: which agent produced the response

This maps to our `sessions.roleName` / `messages.data.agent` fields. See [../architecture/agent-roles.md](../architecture/agent-roles.md) for the full agent-vs-role discussion.

### For Import

When importing OpenCode sessions into hub Postgres:
1. Read from SQLite using the queries in the skill's SKILL.md
2. Map `project.worktree` → `projects.directory` (default workspace)
3. Map `session` fields → our `sessions` table (preserving `parent_id` for coordinator relationships)
4. Map `message.data` → our `messages.data` JSONB column (the shapes are compatible)
5. Map `part.data` → our `parts.data` JSONB column (type discriminator maps directly)

The opencode-memory skill's query patterns are a useful reference for writing an import script, but the import itself should be a hub operation that reads from the SQLite file and inserts into Postgres.

### Important: Read-Only for Now

The skill provides **read-only** access patterns. This is exactly what we need for initial import. Writing back to OpenCode's SQLite is not in scope — the hub is the source of truth going forward.

## References

- opencode-memory SKILL.md: https://github.com/carson2222/skills/raw/refs/heads/main/opencode-memory/SKILL.md
- OpenCode database schema: opencode's session schema (npm package)
- Hub session/message storage: [../architecture/storage/sessions.md](../architecture/storage/sessions.md)
- Hub agent-role model: [../architecture/agent-roles.md](../architecture/agent-roles.md)