Skip to main content
Glama

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: pond

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:

Variable

Purpose

SESSION_VAULT_OPENCODE_DB

Override OpenCode DB path

SESSION_VAULT_CONFIG

Override config file path

SESSION_VAULT_PROVIDER

Override session provider (ocsm/native)

BAIDU_NETDISK_ACCESS_TOKEN

Baidu access token bootstrap

BAIDU_NETDISK_REFRESH_TOKEN

Optional refresh token

BAIDU_NETDISK_CLIENT_ID

Optional OAuth client ID

BAIDU_NETDISK_CLIENT_SECRET

Optional OAuth client secret

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:

File

Description

manifest.json

Metadata, member graph, member_files mapping, checksums

data/<safe-digest>.json

One file per session (filename is a SHA-256 digest, never a raw session ID)

checksums.sha256

SHA-256 of every internal file

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.

Available Tools

10 tools
session_vault_archive_createD
ParametersJSON Schema
NameRequiredDescriptionDefault
labelYes
best_effortNo
session_idsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

session_vault_archive_listD
ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
project_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

session_vault_archive_uploadD
ParametersJSON Schema
NameRequiredDescriptionDefault
archive_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

session_vault_archive_verifyD
ParametersJSON Schema
NameRequiredDescriptionDefault
archive_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

session_vault_project_listD
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

session_vault_remote_copy_listD
ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
archive_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

session_vault_session_listD
ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
project_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

session_vault_tag_addD
ParametersJSON Schema
NameRequiredDescriptionDefault
tagYes
archive_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

session_vault_tag_listD
ParametersJSON Schema
NameRequiredDescriptionDefault
archive_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

session_vault_tag_removeD
ParametersJSON Schema
NameRequiredDescriptionDefault
tagYes
archive_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 10 tool updatesv0.1.0
    • First observedsession_vault_archive_create
    • First observedsession_vault_archive_list
    • First observedsession_vault_archive_upload
    • First observedsession_vault_archive_verify
    • First observedsession_vault_project_list
    • First observedsession_vault_remote_copy_list
    • First observedsession_vault_session_list
    • First observedsession_vault_tag_add
    • First observedsession_vault_tag_list
    • First observedsession_vault_tag_remove

TDQS

C2/5.0

Scored across 10 tools

Disambiguation5/5

Each tool targets a distinct resource-action pair (project, session, archive, remote_copy, tag), with no overlapping functionality. Agents can clearly differentiate between tools.

Naming Consistency5/5

All tools follow a consistent snake_case pattern: 'session_vault_<resource>_<action>'. The naming convention is uniform and predictable.

Tool Count5/5

With 10 tools covering multiple resources (projects, sessions, archives, remote copies, tags), the count is well-scoped and appropriate for a focused session vault management server.

Completeness2/5

The tool set lacks essential CRUD operations for core resources. Projects and sessions only have list functionality, and archives are missing update/delete. These gaps hinder full lifecycle management.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to list, inspect, and export OpenCode AI coding sessions as HTML/JSON archives with secret redaction and token statistics.
    1
    MIT
  • A
    license
    A
    quality
    A
    maintenance
    Lossless archive and search for AI agent sessions (Claude Code, Codex, opencode, pi and others), exposed to agents over MCP. Local-first, written in Rust.
    4
    72
    Apache 2.0
  • A
    license
    Not graded
    quality
    B
    maintenance
    Enables local archiving and searchable recall of AI coding sessions from Claude Code, Codex, Pi, and OpenCode via MCP, allowing agents to access past conversations as context.
    MIT