mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-05-20 16:53:12 -07:00
mkorwel
95 lines
4.2 KiB
Markdown
95 lines
4.2 KiB
Markdown
# Research Proposal: Cloud State Sync
|
|
|
|
This document explores the architectural shift of moving the global `~/.gemini`
|
|
folder to the cloud. The goal is to enable a shared data store for plans,
|
|
settings, and configurations across devices, instances, and sessions while
|
|
maintaining performance, security, and portability.
|
|
|
|
## Objective
|
|
|
|
Transition Gemini CLI from a local-first state management system to a
|
|
distributed, synchronized agent. This allows you to start a task on one machine
|
|
(e.g., a local laptop) and resume it seamlessly on another (e.g., a remote
|
|
workstation or a different office machine).
|
|
|
|
## Data Categorization
|
|
|
|
Not all data within `~/.gemini` should be treated equally. We categorize the
|
|
contents to determine the most effective synchronization strategy.
|
|
|
|
- **Static and Configuration:** `settings.json`, `projects.json`, and `policies/`.
|
|
These are small files with low-frequency updates, making them ideal for simple
|
|
cloud synchronization.
|
|
- **Sensitive and Identity:** `google_accounts.json` and `installation_id`. These
|
|
contain refresh tokens and unique identifiers that require high-grade,
|
|
client-side encryption before leaving the device.
|
|
- **High-Volume and Ephemeral:** `history/`, `tmp/`, and `antigravity/` (browser
|
|
profiles). These are large or frequently updated. Naive synchronization would
|
|
be slow and resource-intensive.
|
|
- **Computed and Environment-Specific:** `extension_integrity.json` and
|
|
`trustedFolders.json`. These often contain absolute local paths that may not
|
|
be valid across different machines or operating systems.
|
|
|
|
## Architectural Approaches
|
|
|
|
We are evaluating three primary methods for implementing cloud synchronization.
|
|
|
|
### Virtual Filesystem (VFS) Layer
|
|
|
|
Implement an abstraction layer for Node.js `fs` calls that transparently
|
|
redirects operations to a cloud provider like GCS or S3.
|
|
|
|
- **Pros:** Requires minimal changes to existing high-level logic.
|
|
- **Cons:** Network latency on every file operation could degrade the user
|
|
experience. Requires a robust local LRU (Least Recently Used) cache.
|
|
|
|
### Git-Ops and Snapshot Syncing
|
|
|
|
Automatically commit and push state changes to a private, hidden repository.
|
|
|
|
- **Pros:** Provides built-in versioning, conflict resolution, and portability.
|
|
- **Cons:** High overhead for frequent, small writes, such as session history
|
|
updates.
|
|
|
|
### Centralized State Server (The "Brain")
|
|
|
|
Communicate with a lightweight service (gRPC or WebSockets) that acts as the
|
|
single source of truth for the agent's state.
|
|
|
|
- **Pros:** Enables real-time synchronization across active sessions.
|
|
- **Cons:** Requires a hosted service and a persistent internet connection.
|
|
|
|
## Technical Considerations
|
|
|
|
The following table outlines the primary technical challenges and proposed
|
|
solutions for a cloud-synced state.
|
|
|
|
| Dimension | Challenge | Potential Solution |
|
|
| :--- | :--- | :--- |
|
|
| **Performance** | Shell startup latency is critical. | **Stale-While-Revalidate:** Load local cache instantly; sync in the background. |
|
|
| **Security** | Secrets management in the cloud. | **Zero-Knowledge Encryption:** Encrypt secrets client-side with a user passphrase. |
|
|
| **Portability** | Inconsistent absolute paths. | **Path Normalization:** Store paths relative to `$HOME` or use UUIDs. |
|
|
| **Conflicts** | Simultaneous edits on multiple devices. | **CRDTs:** Use Conflict-free Replicated Data Types for plans and history. |
|
|
|
|
## Hybrid Strategy Proposal
|
|
|
|
A tiered synchronization model balances performance with portability.
|
|
|
|
1. **Tier 1 (Cloud Native):** Sync settings, plans, and global memories
|
|
immediately via a structured API.
|
|
2. **Tier 2 (Lazy Sync):** Upload session history and logs at the end of a
|
|
session or when explicitly resuming on another device.
|
|
3. **Tier 3 (Local Only):** Keep large caches, browser profiles, and
|
|
environment-specific integrity checks local to the device.
|
|
|
|
## Next Steps
|
|
|
|
To move forward with this proposal, we must perform the following actions:
|
|
|
|
1. Audit the current `~/.gemini` directory to determine the typical data
|
|
volume, particularly within the `history/` folder.
|
|
2. Identify all files within `~/.gemini` that contain environment-dependent
|
|
absolute paths.
|
|
3. Prototype a synchronization provider using a private Git repository or a
|
|
dedicated cloud storage bucket.
|