themis-bridge-mcp

Name: themis-bridge-mcp
Availability: InStock
Author: infinitum nihil

Critical message queue bridge with backup orchestration for continuum persistent memory

GitHub

GitHubスター

ユーザー評価

未評価

フォーク

イシュー

閲覧数

お気に入り

README

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

HTTP API (themis-bridge-server) receives backup trigger
Signal File created in continuum-backups/orchestrated/signals/
MCP Tool (orchestrate_system_backup) processes signal
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