Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/aipoch/open-science/llms.txt

Use this file to discover all available pages before exploring further.

Open Science organizes all research work into two nested concepts: Projects are long-lived research contexts that group related sessions, artifacts, and notebook workspaces under a single name. Sessions are individual conversation threads inside a project — each one a full record of a researcher’s back-and-forth with the agent, along with every tool call, generated file, and notebook execution produced along the way.

Projects

Backed by Prisma/SQLite. Each project has a name, optional description, and an isolated directory for its sessions and artifact store. Projects are created and managed from the app’s Home page and persist indefinitely across app restarts.

Sessions

Stored as JSON files on disk, one per session. Each session belongs to a project and holds the full conversation history, agent state, and metadata needed to resume work exactly where it was left off — even after closing and relaunching the app.

Projects

Projects are the top-level organizational unit in Open Science. The Prisma schema defines the Project model in prisma/schema.prisma:
model Project {
  id          String   @id @default(cuid())
  name        String
  description String   @default("")
  isExample   Boolean  @default(false)
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
}
The shared Project type used across the IPC boundary (from src/shared/projects.ts) normalizes timestamps to epoch milliseconds so the renderer handles them the same way as session timestamps:
export type Project = {
  id: string          // cuid() — generated by Prisma
  name: string
  description: string
  isExample: boolean  // true for built-in example projects
  createdAt: number   // epoch ms
  updatedAt: number   // epoch ms
}
Projects are managed through IPC channels registered in src/main/projects/ipc.ts: projects:create, projects:list, projects:get, projects:update, and projects:delete. The isExample flag marks projects that ship with Open Science as built-in starting points; they are created automatically on first launch and not shown in the delete flow. Each project has its own isolated subtree under the app storage root: session JSON files live at sessions/<projectId>/<sessionId>.json, and artifact files are stored under artifacts/<projectName>/.

Project Preview State

Open Science persists each project’s preview panel configuration in a ProjectPreviewState record (also in SQLite) so the researcher returns to the same view they left:
model ProjectPreviewState {
  projectId    String   @id
  panelState   String         // "open" or "collapsed"
  activeItemId String?        // which tab is focused
  items        String  @default("[]")  // pinned preview items as JSON
  updatedAt    DateTime @updatedAt
}
Runtime-only tabs (such as live notebook output) are not stored in ProjectPreviewState — they are reconstructed from the notebook service on next open.

Sessions

Sessions are conversation threads within a project. Unlike projects, sessions are not stored in SQLite — they live as individual JSON files on disk, managed by the SessionRepository in src/main/session-persistence/repository.ts. Each session file lives at:
sessions/<projectId>/<sessionId>.json
A small manifest.json file at the project level records which session was most recently open, so the app can restore the researcher’s exact working context on next launch.

Session Fields

A persisted session (PersistedChatSession) carries:
FieldDescription
idUnique session ID (used as the ACP protocol session ID after resume)
titleDisplay name shown in the sidebar (editable by the researcher)
projectIdThe owning project
statusidle, running, or waiting-permission
cwdThe resolved working directory for this session’s agent process
Sessions can be renamed and deleted from the sidebar. Deleting a session removes the JSON file from disk but does not delete its associated artifact files — those remain in the project’s artifact store and can still be browsed in the preview workbench.

Multiple Sessions Per Project

A project can have many sessions, all shown in the sidebar. Switching between sessions does not require restarting the agent — the AcpRuntime can hold multiple ActiveSession objects simultaneously, each with its own MCP server configuration and event stream. The renderer switches the active view by changing currentSessionId on the runtime.

Session Persistence and the Save Bridge

Writes to the session store are serialized through a save queue to prevent concurrent corruption. The save bridge diffs the in-memory session store against the on-disk state so only sessions that have actually changed are written — keeping disk I/O proportional to actual mutations rather than writing the full session list on every state change. On first run, the persistence layer migrates any sessions found in the legacy single-file format to the per-project directory structure, idempotently.

Resuming a Session

When a researcher reopens the app, the manifest file tells the app which project and session to load. If that session has a matching ACP session ID in the running agent, resumeSession() reattaches to it:
// src/main/acp/runtime.ts (abridged)
async resumeSession(request: AcpResumeSessionRequest): Promise<AcpCreateSessionResponse> {
  // ...
  const resumeResponse = await connection.agent.request(
    acp.methods.agent.session.resume,
    {
      sessionId: request.sessionId,
      cwd: sessionCwd,
      mcpServers: await this.createMcpServers({ ... }),
      ...this.createSessionMeta()
    }
  )
  // ...
}
Session resume uses the stable persisted session ID as both the ACP session ID and the artifact session ID so that all resumed artifact writes land in the same storage subtree as the original session’s files. The runtime checks supportsSessionResume (negotiated during agent.initialize) before attempting a resume and throws early if the agent backend doesn’t advertise the capability.
Session resume requires that the ACP agent backend advertise sessionCapabilities.resume during the initialization handshake. If the capability is absent, calling resumeSession() throws: "ACP agent does not support session resume." Sessions can still be re-opened for new prompts by creating a fresh session in the same project.

Build docs developers (and LLMs) love