Plugin SDK

Construir para OpenClone

Qualquer linguagem, qualquer fonte de dados. Um POST para um endpoint. Seu plugin escreve no vault automaticamente. Dedup, sanitização e isolamento de tenant incluídos.

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

Registro de plugins

Plugins oficiais e da comunidade. Instale, fork ou use como ponto 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 ↓

Referência API — POST /api/v1/ingest

O único endpoint que seu plugin chama. Envie lotes de eventos, receba contagens de armazenados e ignorados.

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.

Manifesto do plugin — plugin.json

Declare os metadados do seu plugin. Usado para exibição do registro e verificações de permissão.

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 fonte

Cada source_type mapeia para uma pasta do vault e um nível de sensibilidade. Use o mais próximo dos seus dados.

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.

Exemplos de código

Exemplos prontos para usar nas linguagens mais comuns. Substitua a URL, chave e campos de dados.

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"}

Tópicos avançados

Deduplicação

Cada evento é deduplicado no servidor. Defina raw_ref com um ID único estável por evento. O backend faz hash de source_type + plugin_id + raw_ref e ignora duplicatas silenciosamente.

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

Limites de taxa

60 requisições/minuto por chave API. 500 eventos por lote. 1 MB máx. Timestamps após 2020-01-01, não mais de 24h no futuro. Retorna 429 ao exceder o limite. Use backoff exponencial.

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

Processamento em lote

Armazene eventos localmente e envie em lotes. Até 500 eventos por requisição. Todos vão para o mesmo arquivo .md diário. Lotes parciais são suportados.

// 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 seu plugin

Abra um PR no repo PixxzR/openclone. Inclua plugin.json, um README e um script de instalação.

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