Session Vault

OpenCode Session Vault — discover, archive, catalog, and verify OpenCode sessions.

Non-restorable transcript snapshot. Archives contain only session, message, and part rows from the OpenCode database. Restore, rehydration, and import are not supported. Baidu Netdisk upload and the narrow project MCP are available; live-account behavior remains an explicit acceptance gate.

Quick Start

# Install
uv sync

# Optional Baidu support (run sync first, then install the pinned official source)
uv sync --extra baidu
powershell -ExecutionPolicy Bypass -File scripts/install_baidu_netdisk_dep.ps1
powershell -ExecutionPolicy Bypass -File scripts/install_baidu_netdisk_dep.ps1 -Status

# Create a minimal config (optional)
# session-vault.toml
# vault_id = "my-vault"
# allowed_project_roots = ["C:/Users/Me/Projects"]
# opencode_db_path = "C:/path/to/opencode.db"

# Verify setup
uv run session-vault doctor

# List projects
uv run session-vault projects list

# List sessions in a project
uv run session-vault sessions list --project "C:/Users/Me/Projects"

# Create an archive
uv run session-vault archive create \
  --session <session-id> \
  --label "My Archive" \
  --best-effort

# List archives
uv run session-vault archive list

# Verify an archive
uv run session-vault archive verify <archive-id-or-path>

# Upload a cataloged archive and inspect remote state
uv run session-vault remote upload <archive-id>
uv run session-vault remote copies --archive-id <archive-id>

Related MCP server: OpenCode MCP Gateway

Configuration

Create session-vault.toml in the repository root (optional — all keys have defaults):

vault_id = "my-vault"
allowed_project_roots = ["C:/Users/Me/Projects"]

# Override OpenCode DB path (auto-detected otherwise)
# opencode_db_path = "C:/path/to/opencode.db"

# Session provider: "ocsm" (default) or "native" (explicit fallback)
# provider = "ocsm"

# Strict mode: require allowed roots (always enforced in MCP)
# strict_mode = true

# Tune limits
max_archive_members = 10000          # max sessions per archive
max_uncompressed_bytes = 524288000   # 500 MiB
max_compression_ratio = 100.0        # max inflated-to-compressed

[remote]
backend = "baidu"
app_name = "session-vault"
vault_id = "my-vault"
# subdir = "backups"

Environment overrides:

State directory (catalog DB, archives) defaults to %LOCALAPPDATA%\SessionVault\<vault-id>.

Session Provider

Session Vault reads project/session metadata through a pluggable provider abstraction:

• ocsm (default) — delegates read-only queries to the external OpenCode Session Manager CLI, pinned by uv.lock to commit b9d4d1c091161ecc320273948fa87f3d77f6f0fc.

• native — standalone SQLite queries with identical semantics; must be explicitly selected (config or SESSION_VAULT_PROVIDER=native). Never falls back from OCSM silently.

Session Vault owns all policy enforcement (allowed-root validation, project/root uniqueness check, member limit, visited guard), coherent capture (snapshot + revision detection), archive packaging (digest filenames, ZIP building), hostile-archive verification, catalog durability, and idempotency. The provider is strictly read-only SELECT.

Archive Contents (v1)

Each archive ZIP contains:

Tables included: session, message, part (non-restorable transcript snapshot).

Session IDs (including real ses_* identifiers) are opaque text; they are never used as filesystem paths. Only archive IDs are UUIDs.

Baidu Netdisk

The adapter reuses the official baidu-netdisk/mcp source pinned to commit b3983d330fea79c7b72e6b7014803e1830148d2c. That upstream subproject is not directly buildable as a Git dependency, so scripts/install_baidu_netdisk_dep.ps1 clones the exact commit into a temporary directory, adds packaging metadata only to that disposable copy, installs it, records non-secret provenance under %LOCALAPPDATA%, and removes the temporary source and wheel.

Remote archive payloads are committed before an immutable .commit.json sidecar. Catalog state distinguishes pending, committed, failed, and incomplete attempts. Permanent delete, move/recycle, and restore are not exposed.

Project MCP

Start the stdio server with:

uv run session-vault-mcp

The server exposes ten session_vault_* tools for allowed project IDs, sessions, archives, remote copies, and tags. It requires non-empty allowed_project_roots and does not expose arbitrary filesystem/remote paths, credentials, download, rename, delete, move, or restore operations.

Verification

python -m pytest -q -rs
python -m compileall -q src tests

Deterministic tests use an isolated filesystem remote. Real Baidu authentication, upload, download, quota, and rename behavior require manual validation with an account scoped to the configured /apps/<app-name>/ directory.

Attribution

Read-only session queries reuse the installed Git dependency from neuronalism/opencode-session-manager-cli at commit b9d4d1c091161ecc320273948fa87f3d77f6f0fc; no OCSM source is vendored here. Archive safety, verification, catalog, and policy logic remain Session Vault-owned because OCSM does not provide those contracts.

Current Limitations

• Session restore/import is unsupported; archives are non-restorable transcripts.

• Permanent remote delete and unverified move/recycle operations are intentionally unavailable.

• Task Scheduler automation and repository-local OpenCode Agent/Skill/Command presets are not included yet.