Cloud-Assisted Local Fallback
Relevant source files
The following files were used as context for generating this wiki page:
Cloud-Assisted Local Fallback defines a tiered provider policy that prioritizes cloud services for heavy computation while maintaining local autonomy. The system ensures that coding agents remain functional even when internet access fails by falling back to local models and storage.
This architecture treats markdown files as the canonical human truth and utilizes local indexing for primary retrieval. Cloud memory serves only as an optional overlay for session continuity and never acts as the primary source of truth.
Sources: README.md:113-121, CLAUDE.md:25-30
Provider Policy and Service Logic
The system splits operational tasks between cloud-assisted and local-first providers based on the complexity and requirements of the task.
Task Allocation
- Embeddings: The system attempts cloud-assisted generation first. If network access fails, it falls back to local embedding models.
- Summarization and Compression: High-resource tasks like session summarization or context compression use cloud assistance. The system switches to local summarizers if the cloud provider is unavailable.
- Retrieval: The system prioritizes local retrieval against indexed artifacts whenever possible to maintain speed and data privacy.
Sources: README.md:115-121, CLAUDE.md:65-66
Component Responsibilities
| Service Type | Primary Provider | Fallback Provider | Data Ownership |
|---|---|---|---|
| Embeddings | Cloud API | Local Model | Local Zvec Index |
| Summarization | Cloud API | Local Model | Local Markdown |
| Retrieval | Local Index (qmd/Zvec) | N/A | Local Markdown |
| Session Memory | Cloud Overlay | Local Markdown | Local Foundation |
Sources: README.md:58-69, CLAUDE.md:25-30
Data Flow and Fallback Logic
When a tool request initiates, the UnifiedSessionManager or the underlying transport layer determines the provider status. If the primary cloud service returns a failure, the logic triggers the local recovery path.
The diagram shows the decision logic where retrieval bypasses the cloud, while compute tasks attempt the cloud before falling back to the local foundation.
Sources: README.md:113-121, session_manager.py:27-40
Memory Layer Architecture
The architecture maintains a strict hierarchy to prevent retrieval systems from overlapping or conflicting.
Layered Storage
- Canonical Truth: Human-maintained markdown files (design docs, ADRs, module maps) represent the durable state.
- Semantic Recall: The
Zveclayer indexes promoted non-doc artifacts, including investigation summaries and stable code summaries. - Cloud Overlay: Provides continuity across different environments but remains secondary to the local foundation.
Sources: README.md:43-55, CLAUDE.md:25-30
Local Persistence Implementation
The UnifiedSessionManager ensures the local foundation is initialized and ready for fallback by creating the necessary directory structure for sessions, memories, and patterns.
# session_manager.py:27-37
class UnifiedSessionManager:
def __init__(self, memory_bank_path: str = "memory-bank"):
self.memory_bank_path = Path(memory_bank_path)
self.sessions_dir = self.memory_bank_path / "sessions"
self.memories_dir = self.memory_bank_path / "memories"
self.patterns_dir = self.memory_bank_path / "patterns"
self.index_file = self.memory_bank_path / "index.md"
self._ensure_directories()
Sources: session_manager.py:27-37
Token and Context Management
The fallback system respects engineering defaults for context windows, which ensures that local models are not overwhelmed during a fallback event.
- Active Context Ceiling: 64K tokens.
- Compaction Trigger: 45K tokens.
When the system operates in local fallback mode, it utilizes checkpointing at subtask boundaries to compress old context and pass summaries instead of raw transcripts. This prevents the local context window from exceeding the ceiling.
Sources: README.md:92-101, CLAUDE.md:44-46
Session Recovery and Continuity
The architecture supports session restoration after a crash or disconnection. The UnifiedSessionManager reloads the last active session from the local registry upon initialization, ensuring work continues even if the cloud synchronization state is unknown.
The sequence diagram illustrates how the system prioritizes local recovery when the cloud overlay is unreachable.
Sources: session_manager.py:539-548, tests/test_integration.py:245-260
Summary of Fallback Mechanisms
Cloud-Assisted Local Fallback ensures the Sequential Thinking MCP v2 remains a "local-first" tool. While cloud providers enhance the agent's capabilities with better embeddings and summaries, the system treats local markdown files as the ultimate source of truth. This design guarantees reliability in offline environments and provides clear boundaries for context management and semantic retrieval.
Sources: README.md:12-20, CLAUDE.md:65-68