Build for OpenClone
Any language, any data source. POST to one endpoint. Your plugin writes to the vault automatically. Dedup, sanitization, and tenant isolation are handled for you.
Plugin Registry
Official and community plugins. Install, fork, or use as a starting point for your own.
Mac System Audio
System audio capture via ScreenCaptureKit + Whisper STT. Captures all app audio including meetings.
audio_system openclone-mac-audio Mac Screen OCR
Screenshots active window every 30s + Apple Vision OCR. Captures everything you read and write.
screen_ocr openclone-mac-screen Browser Extension
Captures browsing history, reading time, and article content. Manifest V3.
web_browsing openclone-browser Microphone
Ambient microphone capture via AVFoundation + Whisper STT. Voice notes and conversations.
audio_mic openclone-mac-mic Voice Journal
Voice notes from the mobile or desktop app. Transcribed and stored in Journal/.
journal Windows Audio
WASAPI Loopback capture — all app audio.
Windows Screen
DXGI capture + WinRT OCR.
Linux Audio
PulseAudio/PipeWire monitor source.
Linux Screen
X11/Wayland screenshot + Tesseract OCR.
Health
HealthKit + Health Connect. Steps, sleep, HR, HRV.
Calendar
EventKit + Google Calendar API.
Obsidian
Filesystem watcher on your Obsidian vault.
Spotify / Last.fm
Last.fm scrobbling — works with any music player.
API Reference — POST /api/v1/ingest
The single endpoint your plugin calls. Send batches of events, get back a count of stored vs skipped.
Request body
{
"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 |
X-API-Key: your-api-key in every request.
Get your key from backend/.env → API_KEY.
Plugin Manifest — plugin.json
Declare your plugin metadata. Used by the backend for registry display and permission checks.
{
"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) |
GET /api/v1/plugins).
Source Types
Each source_type maps to a vault folder and a sensitivity level. Use the closest match for your data.
| 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/ | 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 |
openclone.enabled: false.
Code Examples
Drop-in examples for the most common languages. Replace the URL, key, and data fields.
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"} Advanced Topics
Deduplication
Each event is deduplicated server-side. Set raw_ref to a stable unique ID per event. The backend hashes source_type + plugin_id + raw_ref and skips duplicates silently.
Rate Limits
60 requests/minute per API key. 500 events per batch. 1 MB max payload. Timestamps must be after 2020-01-01 and no more than 24h in the future. Returns 429 on limit exceeded. Retry with exponential backoff.
Batch Events
Buffer events locally and send in batches for efficiency. Up to 500 events per request. All events in a batch are written to the same daily .md file. Partial batches are supported. Skipped events do not block stored ones.
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
Create plugin.json
Declare your plugin ID, platform, and source type.
"source_type": "braindump" POST your first event
Use the curl example above — one command, 30 seconds.
{"stored": 1} Verify in vault
Open the vault folder. Your .md file is ready.
Braindump/2026-02-26.md Publish Your Plugin
Open a PR to the PixxzR/openclone repo to add your plugin to the official registry. Include plugin.json, a README, and an install script.
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