English | 中文

Agent Session Vault

Local-first session projection and Tokscale aggregation jobs on OPL Fleet

Fleet-wide Dispatch · Projection Delta-First · Tokscale Views · Archive-Ready Storage

Primary Use Manage session history that lives across machines, clients, and project-level roots without promoting a cloud drive into the source of truth

Interface Python CLI for config inspection, sync orchestration, Tokscale projection, storage summaries, and archive workflows

Current Flagship Making Tokscale usable when histories span Codex, Gemini CLI, OpenClaw, multiple machines, and multiple roots

The default product contract is a compact analytics projection that Tokscale can continuously recompute and submit. Full conversation migration is an explicit optional capability, not part of the daily default.

Product Position

Modern agent session history rarely sits in one clean directory. It usually spreads across:

• home-level roots such as ~/.codex, ~/.gemini, and ~/.openclaw
• project-scoped roots such as ~/workspace/<project>/.codex
• multiple machines, including macOS, Linux, and WSL2
• long-running workflows that create replay-heavy or storage-heavy histories

agent-session-vault is the layer that makes those histories manageable without patching upstream clients or treating OneDrive, NAS, or iCloud as the authority.

What It Helps You Do

• Discover session roots per machine, per client, and per project directory.
• Sync across machines with projection delta-first as the default path.
• Build both raw and canonical views for Tokscale.
• Keep explicit raw sync and archive flows for colder or heavier storage paths.
• Treat directory relays as transport surfaces instead of embedding cloud-provider logic into the tool.

Why Tokscale Needs This

Tokscale is a strong exporter, but it is not the control plane for:

• cross-machine session discovery
• project-level root discovery
• relay bundles and projection deltas
• canonicalization rules such as explicit OMX-style replay dedupe
• archive planning for old raw trees

agent-session-vault prepares the session view that Tokscale should read. It does not modify Tokscale upstream.

Quick Start

Clone the repository and install the CLI:

git clone <your-repo-url> agent-session-vault
cd agent-session-vault
uv tool install --python 3.12 --editable .

uv tool owns the Python 3.12 environment and exposes the CLI from its managed binary directory (normally ~/.local/bin). Scheduled automation should invoke that resolved executable by absolute path instead of depending on an inherited shell PATH.

Create a local config:

mkdir -p ~/.config/agent-session-vault
cp config/agent-session-vault.example.toml ~/.config/agent-session-vault/config.toml

The real config lives outside the checkout by design. Keep actual machine names, SSH targets, usernames, absolute paths, and operational output in that local config and under the configured state roots. Do not copy session data, bundles, receipts, or logs into the repository.

Fleet-managed nodes do not need duplicate machine definitions in ~/.config/agent-session-vault/config.toml. Run the common path directly:

agent-session-vault config --json
agent-session-vault sync fleet --json
agent-session-vault tokscale exec --mode raw -- submit -c codex,gemini,openclaw --dry-run

If you want the stricter internal accounting view:

agent-session-vault tokscale exec --mode canonical --omx-replay-dedupe strict -- submit -c codex,gemini,openclaw --dry-run

Common Workflows

Inspect loaded config:

agent-session-vault config --json

Inspect storage:

agent-session-vault storage summary --json
agent-session-vault storage migration-plan --json

Run the default OPL Fleet-wide projection sync:

agent-session-vault sync fleet --json

OPL Fleet owns the node registry, standard Python/SSH baseline, fresh admission, task dispatch, and artifact route. This repository owns session projection, incremental state, import, and Tokscale semantics. Every approved Fleet node is considered automatically; nodes do not declare a separate Session Vault capability, and an ineligible node is skipped with an explicit admission reason.

Refresh the current HOME analytics projection directly:

agent-session-vault sync local-home-projection --json

Sync volatile local Codex runtime homes into an append-only Tokscale extras tree:

agent-session-vault sync local-codex \
  --source /path/to/quest-or-runtime-root \
  --json

Run the deterministic daily projection sync and Tokscale submission workflow:

agent-session-vault ops daily-tokscale --mirror-stable --json

The command first incrementally projects the controller's local HOME, then asks OPL Fleet to run the same projection job on every approved node that passes fresh data-job admission. Fleet returns the remote projection artifacts to the controller; nodes never run independent Tokscale submits. The controller builds one projection-only raw view, takes one process lock, and performs exactly one aggregate submit. Tokscale resolves duplicate Codex active/archive copies by session identity, while Session Vault keeps machine roots separate and verifies that the same frozen view, Tokscale version, pricing, and dedupe policy produce the same totals regardless of the eligible execution node. After a confirmed submit, --mirror-stable writes the analytics layer as incrementally reusable zstd shards so OneDrive does not have to manage tens of thousands of small files.

Restoring the default analytics stable layer is sufficient for Tokscale continuity. If complete conversation text, search, or session resumption is also required, explicitly inspect the optional full-fidelity migration without starting the potentially large copy:

agent-session-vault storage mirror-stable --include-live-sessions --dry-run --json

Verify a packed stable restore:

agent-session-vault storage restore-stable --dest-root /path/to/restore-staging --json

Prepare Tokscale environment only:

agent-session-vault tokscale env --mode raw --json
agent-session-vault tokscale env --mode canonical --omx-replay-dedupe strict --json

Archive a cold tree:

agent-session-vault archive offload-tree \
  --source ~/.config/tokscale/imports/machine-a/.raw/codex \
  --bundle-name machine-a-codex-raw \
  --json

Current Boundaries

• OPL Fleet is the only multi-machine node, network, admission, and dispatch control plane; Session Vault does not maintain another one.
• Session Vault is a standard Fleet data job, not a per-node capability or installation requirement.
• Approved nodes run projection work; one controller owns the aggregate raw view, run lock, and exactly-once Tokscale submit.
• Cross-node numerical parity requires the same frozen projection inputs, Tokscale package, custom pricing, and dedupe policy; it does not require copying the full aggregate dataset to every node.
• projection delta-first is the default cross-machine path; full raw sync remains explicit.
• The default raw Tokscale view is projection-only; live local client roots are not scanned directly.
• The default stable mirror guarantees Tokscale analytics continuity; full-fidelity conversation migration is optional and explicit.
• Cloud sync tools are treated as directory relays, not first-class backends.
• The current flagship client set is Codex, Gemini CLI, and OpenClaw.
• This repository manages session views and transport, not provider billing truth.
• Live client roots are not destructively rewritten.

For Agents

Use the repository CLI rather than re-implementing sync, projection, or archive logic.

Typical agent tasks:

• enroll machines through OPL Fleet and run sync fleet
• use configured machine/root rules only for legacy compatibility or focused diagnostics
• run ops daily-tokscale --json for routine sync and submit automation
• run sync auto <machine> only for the legacy or diagnostic path
• run sync local-codex --source <root> before Tokscale when local Codex sessions live under volatile runtime homes
• build raw or canonical Tokscale views
• offload older raw trees into archive bundles when local storage should shrink

Documentation

• Docs index (English)
• Configuration guide (English)
• Architecture guide (English)
• Agent guide (English)
• 文档索引（中文）
• 配置说明（中文）
• 架构说明（中文）
• Agent 使用指南（中文）

Internal planning notes remain repo-local and Chinese-first unless they are explicitly promoted into the public bilingual surface.

Technical Validation

ruff check .
python3 -m pytest

License

Licensed under the Apache License 2.0.