@airjelly/sdk

⚠️ Install only from the official scope: @airjelly/sdk. Any airjelly-sdk (without scope) is not published by us.

Official TypeScript SDK for AirJelly — query memories, tasks, events, app usage, and daily content feeds from any Node.js process on the same machine. Everything stays on 127.0.0.1; no data leaves your machine.

Install

npm i @airjelly/sdk
# or
bun add @airjelly/sdk

Requires Node 18+ and the AirJelly Desktop app running.

Quick start

import { createClient } from '@airjelly/sdk'

const client = createClient()

// Check connection
const health = await client.healthCheck()
console.log(`Connected to AirJelly v${health.version}`)

// Search memories
const memories = await client.searchMemory('hackathon planning', { limit: 5 })
for (const m of memories) {
  console.log(`- ${m.title} (${m.memory_type})`)
}

// Create a task
const task = await client.createTask({ title: 'Review SDK examples' })
console.log(`Created ${task?.id}`)

How auth works

AirJelly Desktop writes runtime.json on startup with { port, token, pid, version } (chmod 600). createClient() reads it automatically — no configuration needed.

| Platform | Path | |---|---| | macOS | ~/Library/Application Support/AirJelly/runtime.json | | Windows | %APPDATA%\AirJelly\runtime.json | | Linux | $XDG_CONFIG_HOME/AirJelly/runtime.json |

Manual override (tests / remote-forwarded setups):

const client = createClient({ port: 41234, token: 'abc123...' })

API overview

| Domain | Methods | |---|---| | Memory | searchMemory, listMemories, getMemory, resolveScreenshotPaths, getEventsByDate | | Knowledge | listPersons, getEventsForEntity | | Tasks | getTask, getTaskList, getOpenTasks, getTaskMemories, createTask, updateTask, completeTask, reopenTask, snoozeTask, archiveTask, unarchiveTask | | App usage | getDailyAppUsage, getAppUsageRange, getTopApps, getAppSessions, getAppIcons | | Reminders | dismissReminder, snoozeReminder | | Recording | getRecordingStatus, getRecordingPermissions, getRecordingStats, startRecording ⚠️, stopRecording ⚠️ |

⚠️ startRecording / stopRecording are side-effectful — they toggle AirJelly's core data collection. Call only when the user has explicitly asked for it.

All methods are typed. Discover what your AirJelly version supports:

const caps = await client.getCapabilities()
console.log(caps.apiVersion, caps.methods)

For methods not yet wrapped, use the escape hatch:

const data = await client.rpc<MyType>('methodName', [arg1, arg2])

Error handling

import { AirJellyNotRunningError, AirJellyConnectionError } from '@airjelly/sdk'

try {
  const tasks = await client.getOpenTasks(5)
} catch (err) {
  if (err instanceof AirJellyNotRunningError) {
    console.error('Start AirJelly Desktop and try again.')
  } else {
    throw err
  }
}

Error classes: AirJellyNotRunningError, AirJellyConnectionError, AirJellyRpcError, AirJellyMethodNotSupportedError, AirJellyApiVersionMismatchError.

Security

• Server binds to 127.0.0.1 only — never network-reachable.
• Auth via bearer token in runtime.json (chmod 600), regenerated on every AirJelly restart.
• Any local process running as your OS user can read runtime.json. Only install SDK wrappers from trusted sources.
• The public API does not expose shell or file-system access to external clients.
• searchMemory and createTask trigger server-side LLM / embedding calls and consume your AirJelly credits.

Report security issues privately to [email protected].

Support

Questions or bug reports: [email protected]

This package is distributed as a compiled binary. Source code is not public.