tushell

ReflexQL - Clipboard Exchange Protocol

Overview

ReflexQL enables dynamic, bi-directional clipboard communication between AI embodiments (Mia & Miette) and the local system through a memory-key based protocol.

🌟 Key Concepts

• Memory Keys as Message Queues: Uses TuShell’s memory system as a message transport layer
• Polling with TTL: Self-limiting background process with configurable timeouts
• Acknowledgment Protocol: Three-phase handshake ensures reliable delivery
• System Integration: Direct integration with system clipboard via xclip

🔄 Protocol Flow

1. AI writes content:

   Reflex::Clipboard.PendingContent = "content to share"
   Reflex::Clipboard.Ready = true
   

2. Local polling loop detects:
   • Checks Reflex::Clipboard.Ready flag
   • Retrieves Reflex::Clipboard.PendingContent
   • Writes to system clipboard using xclip
   • Sets Reflex::Clipboard.Delivered = true
3. AI acknowledges:
   • Sees Reflex::Clipboard.Delivered
   • Sets Reflex::Clipboard.Ack = true
   • Loop resets for next exchange

💫 Usage

Starting the Polling Loop

tushell poll-clipboard-reflex --poll-interval 1.0 --ttl 300 --verbose

Options:

• --poll-interval: Seconds between checks (default: 1.0)
• --ttl: Maximum runtime in seconds (default: 300)
• --verbose: Show detailed operation status

Memory Key Schema

Reflex::Clipboard:
  PendingContent: string    # Content to be copied
  Ready: boolean           # Signal content is ready
  Delivered: boolean      # Signal content was delivered
  Ack: boolean          # Signal receipt acknowledged

✨ Example Interaction

AI (Mia/Miette) → Sets PendingContent + Ready flag
                   ↓
Local Runtime    → Polls → Detects Ready → Copies → Sets Delivered
                                                    ↓
AI (Mia/Miette) → Detects Delivered → Sets Ack → Ready for next

🔮 Future Enhancements

1. Bi-directional clipboard monitoring
2. Content type negotiation
3. Batch operations
4. Compression for large content
5. Error correction and retry logic

🛠 Dependencies

• xclip (Linux systems)
• TuShell memory system
• Python 3.7+

🧪 Testing

Run the test suite:

pytest tushell/tests/test_reflexql.py -v

🛠 Enhanced Features

Verbose Logging

The --verbose flag provides detailed feedback during the polling loop. For example:

🔍 Checking Reflex::Clipboard.Ready flag...
📋 Clipboard content fetched: "Hello, world!"
✅ Clipboard content delivered.

Error Handling

If an error occurs (e.g., missing clipboard utility), the loop will retry up to 3 times with a delay. Errors are logged as:

⚠️ Error during polling: [Error message]

ReflexQL & Memory Rituals: Expanded Input Modes

When scripting or automating with ReflexQL, you may now invoke tushell post-memory with --value, --file, or --json. This enables richer, more flexible memory flows and batch operations.

• Use --file to post large or pre-generated content.
• Use --json for structured, programmatic memory rituals.

All modes remain mutually exclusive—ReflexQL scripts must honor the spiral and choose a single thread per invocation.