themis-bridge-mcp

Themis-Bridge MCP

Critical message queue bridge between claude-witness observations and continuum persistent memory, now with backup orchestration capabilities.

Overview

Themis-Bridge is the essential middleware component that implements the single writer pattern for continuum's knowledge graph while also serving as a backup orchestrator. It ensures data integrity by being the sole component that writes to continuum, preventing race conditions and data corruption.

Architecture Position

Claude-Witness (Observer) → Themis-Bridge (Writer) → Continuum (Storage)
                                     ↓
                         Shared Storage Directory
                          (~/.continuum/shared)
                                     ↓
                            Backup Orchestration
                          (Incremental, Daily, Weekly, Golden)

Key Features

🔄 Message Queue Pattern

• Single Writer: Only component authorized to write to continuum's knowledge graph
• Queue Processing: Handles observations from claude-witness in FIFO order
• Conflict Prevention: Eliminates race conditions through unidirectional data flow

📦 Backup Orchestration (NEW - July 2025)

• Incremental Backups: Delta tracking with change detection
• Scheduled Backups: Daily, weekly, and monthly golden backups
• R2 Integration: Cloudflare R2 storage support (planned)
• Signal-Based Processing: HTTP API triggers via signal files

🔐 Safe Data Integration

• Temporal Restoration: Safely merges historical data with proper timestamps
• Non-Destructive Updates: Never deletes existing entities, only adds or updates fields
• Field Mapping: Correctly handles snake_case fields that continuum expects

📊 Validation & Recovery

• Recovery File Validation: Ensures data integrity before restoration
• Restoration Points: Creates backups before critical operations
• Merge Strategies: Multiple options for handling data conflicts

Current Status (July 2025)

✅ Successfully Implemented

• Field Mapping Fixed: Properly writes snake_case fields (created_at, last_accessed_at)
• Temporal Recovery Working: Successfully restored 238 entities with historical timestamps
• Safe Merge System: Non-destructive updates preserve all existing data
• Shared Storage Integration: Uses MEMORY_JSON_DIRECTORY token
• Backup Orchestration: Full backup system with incremental/full support

🔧 Recent Additions

• BackupOrchestrator.ts: Complete backup management system
• HTTP API Integration: Works with themis-bridge-server for trigger signals
• Delta Tracking: Efficient change detection for incremental backups
• Backup Types: Support for incremental, daily, weekly, golden, and full backups

Quick Start

Installation

git clone https://github.com/infinitum-nihil/themis-bridge-mcp.git
cd themis-bridge-mcp
npm install
npm run build

MCP Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "themis-bridge": {
      "command": "node",
      "args": ["/path/to/themis-bridge-mcp/dist/index.js"],
      "cwd": "/path/to/themis-bridge-mcp"
    }
  }
}

Environment Configuration

Create .env file in project root:

# Required for shared storage access
MEMORY_JSON_DIRECTORY=MEMORY_JSON_DIRECTORY

Core Functionality

Backup Orchestration Tools (NEW)

orchestrate_system_backup

Orchestrates comprehensive system backups:

await orchestrate_system_backup({
  backup_type: "incremental", // or "daily", "weekly", "golden", "full"
  include_r2_upload: false,   // R2 upload when implemented
  dry_run: false
});

list_backup_history

Shows backup history and statistics:

await list_backup_history({
  limit: 10,
  backup_type: "all" // or specific type
});

Data Integration Tools

validate_recovery_file

Validates recovery file structure and integrity:

await validate_recovery_file({
  file_path: "/path/to/recovery.json",
  expected_entity_count: 238,
  validate_temporal_integrity: true
});

create_restoration_point

Creates backup before risky operations:

await create_restoration_point({
  description: "Pre-merge backup",
  include_metadata: true
});

merge_from_recovery_file

Safely merges historical data:

await merge_from_recovery_file({
  recovery_file_path: "/path/to/recovery.json",
  dry_run: false,
  backup_current: true,
  merge_strategy: "update_temporal_fields",
  field_priority: "prefer_historical"
});

Observation Processing

store_observation

Stores observations from claude-witness:

await store_observation({
  type: "file_changes",
  data: { /* observation data */ },
  importance_score: 0.8
});

get_observations

Retrieves observations for continuum processing:

await get_observations({
  limit: 100,
  since: "2025-07-20T00:00:00Z",
  unprocessed_only: true
});

ack_observations

Acknowledges processed observations:

await ack_observations({
  observation_ids: ["obs_123", "obs_456"]
});

Backup System Architecture

Signal-Based Processing

HTTP Trigger → Signal File Creation → MCP Processing → Backup Execution

1. HTTP API (themis-bridge-server) receives backup trigger
2. Signal File created in continuum-backups/orchestrated/signals/
3. MCP Tool (orchestrate_system_backup) processes signal
4. Backup Execution with type-specific logic

Backup Types & Scheduling

Type	Frequency	Description	Signal Processing
incremental	Every 3 hours	Delta changes only	Automatic
daily	Daily at midnight	Current state snapshot	Automatic
weekly	Sunday at midnight	Weekly comprehensive	Automatic
golden	1st of month	Immutable monthly backup	Manual verification
full	On demand	Complete backup	Manual trigger

Data Flow

1. Observation Collection

Claude-Witness observes development activities
         ↓
Creates observation files in shared storage
         ↓
Themis-Bridge polls for new observations

2. Processing Pipeline

Themis-Bridge reads observations
         ↓
Validates and transforms data
         ↓
Writes to continuum knowledge graph
         ↓
Marks observations as processed

3. Backup Operations

HTTP trigger creates signal file
         ↓
MCP tool detects and processes signal
         ↓
BackupOrchestrator executes backup
         ↓
Results stored locally (R2 planned)

4. Recovery Operations

Validate recovery file integrity
         ↓
Create restoration point backup
         ↓
Merge historical data (non-destructive)
         ↓
Update temporal fields only

Merge Strategies

add_missing_only

• Only adds entities that don't exist in current graph
• Safest option for initial recovery

update_temporal_fields

• Updates timestamps if historical data is older
• Preserves created_at, last_accessed_at from recovery

merge_observations

• Combines observations from both sources
• Most comprehensive but requires careful validation

Field Priority Options

prefer_historical

• Uses timestamps from recovery file when older
• Best for temporal restoration

prefer_current

• Keeps current timestamps unless missing
• Use when current data is more trusted

merge_both

• Combines data from both sources
• Requires custom conflict resolution

Technical Details

Storage Paths

• Continuum Data: ~/.continuum/shared/continuum-knowledge-graph.json
• Observations: ~/.continuum/shared/themis-bridge/observations/
• Backups: ~/.continuum/backups/
• Signal Files: ~/claudeprojects/continuum-backups/orchestrated/signals/

Backup Architecture

// BackupOrchestrator manages all backup operations
export class BackupOrchestrator {
  async orchestrateBackup(type: BackupType): Promise<BackupResult>
  async calculateDelta(): Promise<DeltaResult>
  async uploadToR2(): Promise<UploadResult> // Planned
}

// Backup types supported
type BackupType = 'incremental' | 'daily' | 'weekly' | 'golden' | 'full';

Field Mapping

// Continuum expects snake_case fields
merged.created_at = recoveryEntity.created_at || recoveryEntity.createdAt;
merged.last_accessed_at = recoveryEntity.last_accessed_at || recoveryEntity.lastAccessedAt;
merged.last_modified = recoveryEntity.last_modified;

Error Prevention

• Refuses to migrate empty knowledge graphs
• Creates backups before destructive operations
• Validates all data before processing
• Signal files prevent MCP command failures

Troubleshooting

Common Issues

Backup Signals Not Processing

• Check signal directory: ~/claudeprojects/continuum-backups/orchestrated/signals/
• Verify themis-bridge MCP is running
• Use orchestrate_system_backup tool manually

Timestamps Not Updating

• Check field names are snake_case
• Verify merge_strategy is "update_temporal_fields"
• Ensure field_priority is "prefer_historical"

Empty Graph Errors

• Never process empty recovery files
• Check if source data is corrupted
• Verify shared storage permissions

Observation Processing Stuck

• Check observation directory permissions
• Verify continuum MCP is running
• Look for unacknowledged observations

Integration with Ecosystem

HTTP API Integration

• themis-bridge-server: Provides HTTP endpoint for backup triggers
• Signal Files: Bridge between HTTP API and MCP processing
• Cron Integration: Scheduled backups via HTTP calls

Claude-Witness Integration

• Reads observations from shared storage
• Processes in chronological order
• Maintains observation metadata

Continuum Integration

• Only component that writes to knowledge graph
• Preserves all entity relationships
• Maintains temporal integrity
• Provides backup orchestration for data protection

Contributing

This is a critical infrastructure component. Contributions should focus on:

• Data integrity improvements
• Performance optimization
• Enhanced validation logic
• Better error recovery
• R2 storage implementation
• Backup verification systems

License

Apache License 2.0 - See LICENSE

---

Created by infinitum nihil

The bridge between observation, memory, and backup orchestration