Plugin SDK

Construir para OpenClone

Cualquier lenguaje, cualquier fuente de datos. POST a un endpoint. Tu plugin escribe en el vault automáticamente. Dedup, saneamiento y aislamiento de tenant incluidos.

1 endpoint · 15 source types · 500 events/batch · Any language

Registro de plugins

Plugins oficiales y de la comunidad. Instala, haz fork o úsalos como punto de partida.

● Stable

Mac System Audio

macOS

System audio capture via ScreenCaptureKit + Whisper STT. Captures all app audio including meetings.

audio_system openclone-mac-audio
● Stable

Mac Screen OCR

macOS

Screenshots active window every 30s + Apple Vision OCR. Captures everything you read and write.

screen_ocr openclone-mac-screen
Beta

Browser Extension

Chrome/Firefox

Captures browsing history, reading time, and article content. Manifest V3.

web_browsing openclone-browser
● Stable

Microphone

macOS / iOS

Ambient microphone capture via AVFoundation + Whisper STT. Voice notes and conversations.

audio_mic openclone-mac-mic
● Stable

Voice Journal

iOS / macOS

Voice notes from the mobile or desktop app. Transcribed and stored in Journal/.

journal
Planned

Windows Audio

Windows

WASAPI Loopback capture — all app audio.

Planned

Windows Screen

Windows

DXGI capture + WinRT OCR.

Planned

Linux Audio

Linux

PulseAudio/PipeWire monitor source.

Planned

Linux Screen

Linux

X11/Wayland screenshot + Tesseract OCR.

Planned

Health

iOS/Android

HealthKit + Health Connect. Steps, sleep, HR, HRV.

Planned

Calendar

All

EventKit + Google Calendar API.

Planned

Obsidian

All

Filesystem watcher on your Obsidian vault.

Planned

Spotify / Last.fm

All

Last.fm scrobbling — works with any music player.

View all on GitHub → · Want to build one? Read on ↓

Referencia API — POST /api/v1/ingest

El único endpoint que llama tu plugin. Envía lotes de eventos, recibe el conteo de almacenados y omitidos.

Request body

POST /api/v1/ingest Content-Type: application/json
{
  "source_type": "audio_system",
  "platform": "macos",
  "device_id": "550e8400-e29b-41d4-a716-446655440000",
  "plugin_id": "openclone-mac-audio",
  "plugin_version": "1.0.0",
  "timestamp": 1708258800.0,
  "events": [
    {
      "timestamp": 1708258800.0,
      "data": {
        "text": "We discussed the product roadmap for Q2.",
        "duration": 60,
        "app_name": "Google Meet",
        "confidence": 0.95
      },
      "raw_ref": "chunk-2026-02-18-14h30-001"
    }
  ]
}

Response (200)

{
  "stored": 3,
  "skipped": 1,
  "file": "Audio/2026-02-26.md"
}

Error codes

401 Invalid or missing X-API-Key
422 Validation error (field details in body)
429 Rate limit exceeded — retry with backoff
500 Storage error — vault write failed

Field reference

Field Type Required Constraints
source_type string yes One of 15 defined types (see below)
platform string yes macos · windows · linux · ios · android · web
device_id string yes UUID v4 — stable across sessions
plugin_id string yes Kebab-case, max 64 chars, alphanumeric + hyphens
plugin_version string yes Semver (1.0.0)
timestamp float yes Unix epoch — not before 2020-01-01, not > +24h
events array yes 1–500 events per request
events[].timestamp float yes Per-event timestamp (same constraints)
events[].data object yes Source-type-specific fields (see Source Types)
events[].raw_ref string no Your unique ID for deduplication — recommended
Auth: Include X-API-Key: your-api-key in every request. Get your key from backend/.env → API_KEY.

Manifiesto del plugin — plugin.json

Declara los metadatos de tu plugin. Usado para mostrar el registro y las verificaciones de permisos.

plugin.json
{
  "id": "my-audio-plugin",
  "name": "My Audio Capture",
  "version": "1.0.0",
  "platform": ["macos"],
  "source_types": ["audio_system"],
  "sensitivity": "MEDIUM",
  "requires_permissions": ["screen_recording"],
  "config_schema": {
    "chunk_duration": { "type": "integer", "default": 60 },
    "blocklist": { "type": "array", "default": ["Spotify", "Music"] }
  }
}

Field reference

Field Notes
id Unique kebab-case identifier
name Display name in registry
version Semver string
platform macos · windows · linux · ios · android · web
source_types Which source_types this plugin writes
sensitivity LOW · MEDIUM · HIGH · CRITICAL
requires_permissions Platform permissions needed (optional)
config_schema User-configurable settings with defaults (optional)
Place plugin.json at the root of your plugin directory. The backend reads it at startup and registers your plugin in the registry endpoint (GET /api/v1/plugins).

Tipos de fuentes

Cada source_type se mapea a una carpeta del vault y un nivel de sensibilidad. Usa el más cercano a tus datos.

source_type Vault folder Sensitivity Typical data fields
audio_system Audio/ MEDIUM text, duration, app_name, confidence
audio_mic Audio/ HIGH text, duration, confidence
screen_ocr Screen/ MEDIUM text, app_name, window_title, url
journal Journal/ LOW text, duration
web_browsing Web/ MEDIUM url, title, domain, reading_time
music Music/ LOW track, artist, album, duration
health Health/ HIGH steps, heart_rate, sleep_hours
calendar Calendar/ LOW title, start, end, attendees, location
notes Notes/ LOW title, text, tags
gps Location/ MEDIUM lat, lon, accuracy, place_name
photos Photos/ MEDIUM filename, location, timestamp
email Email/ CRITICAL subject, from, to, date (no body)
messaging Messages/ CRITICAL platform, from, preview (local only)
activity Activity/ LOW app_name, duration, category
braindump Braindump/ LOW text
Note on HIGH/CRITICAL types: Always inform users before activating plugins with HIGH or CRITICAL sensitivity. These types capture personal data that users may not want recorded automatically. The backend enforces no technical restriction, but your plugin should default to openclone.enabled: false.

Ejemplos de código

Ejemplos listos para usar en los lenguajes más comunes. Reemplaza la URL, la clave y los campos de datos.

curl — quickest way to test
curl -X POST http://localhost:8000/api/v1/ingest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "source_type": "braindump", "platform": "macos",
    "device_id": "test-001", "plugin_id": "my-plugin",
    "plugin_version": "1.0.0", "timestamp": 1708258800.0,
    "events": [{"timestamp":1708258800.0,"data":{"text":"Hello!"},"raw_ref":"e1"}]
  }'

# Response: {"stored":1,"skipped":0,"file":"Braindump/2026-02-26.md"}

Temas avanzados

Deduplicación

Cada evento se deduplica en el servidor. Establece raw_ref en un ID único estable por evento. El backend hashea source_type + plugin_id + raw_ref e ignora silenciosamente los duplicados.

// In your event:
"raw_ref": "chunk-abc123"
// Backend hashes:
source_type + plugin_id + raw_ref
// Duplicate → skipped

Límites de velocidad

60 solicitudes/minuto por clave API. 500 eventos por lote. 1 MB máx. Timestamps después de 2020-01-01, no más de 24h en el futuro. Devuelve 429 al superar el límite. Usa backoff exponencial.

60 req / min / key
500 events / batch
1 MB max payload
429 → retry with backoff

Procesamiento por lotes

Almacena eventos localmente y envíalos en lotes. Hasta 500 eventos por solicitud. Todos van al mismo archivo .md diario. Se admiten lotes parciales.

// Recommended pattern:
buffer = []
buffer.append(event)
// Every 60s or 100 events:
ingest(buffer[:500])
buffer.clear()
Timestamp rules: Events must have timestamps between 2020-01-01 and now + 24h. Out-of-range timestamps are rejected with a 422. Always use the event's actual capture time, not the send time.

5 minutes to your first memory entry

1

Create plugin.json

Declare your plugin ID, platform, and source type.

"source_type": "braindump"
2

POST your first event

Use the curl example above — one command, 30 seconds.

{"stored": 1}
3

Verify in vault

Open the vault folder. Your .md file is ready.

Braindump/2026-02-26.md

Publicar tu plugin

Abre una PR en el repo PixxzR/openclone para añadir tu plugin al registro oficial. Incluye plugin.json, un README y un script de instalación.

PR checklist

  • plugin.json with all required fields
  • README.md with install instructions
  • install.sh (macOS) or setup instructions
  • No hardcoded API keys or personal data
  • Defaults to openclone.enabled: false
  • Source type matches one of the 15 defined types