Creating a Plugin

Plugins add content processors and agent tools to EchOS without modifying core code. Each plugin is a separate workspace package in plugins/.

Steps

Scaffold the package

mkdir -p plugins/my-plugin/src

Create plugins/my-plugin/package.json:

{
  "name": "@echos/plugin-my-plugin",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch",
    "typecheck": "tsc --noEmit",
    "clean": "rm -rf dist"
  },
  "dependencies": {
    "@echos/shared": "workspace:*",
    "@echos/core": "workspace:*",
    "@mariozechner/pi-agent-core": "^0.52.12",
    "@mariozechner/pi-ai": "^0.52.12",
    "pino": "^9.14.0",
    "uuid": "^13.0.0"
  },
  "devDependencies": {
    "@types/node": "^25.2.3",
    "@types/uuid": "^11.0.0",
    "typescript": "^5.7.0"
  }
}

Create plugins/my-plugin/tsconfig.json:

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src"]
}

Write the processor

Create plugins/my-plugin/src/processor.ts — the logic that fetches/transforms external content:

import type { Logger } from 'pino';
import { validateUrl, sanitizeHtml } from '@echos/shared';
import type { ProcessedContent } from '@echos/shared';

export async function processMyContent(
  url: string,
  logger: Logger,
): Promise<ProcessedContent> {
  const validatedUrl = validateUrl(url); // SSRF prevention — required
  logger.info({ url: validatedUrl }, 'Processing content');

  // Fetch and extract content...
  const title = sanitizeHtml(rawTitle);   // Always sanitize external content
  const content = sanitizeHtml(rawContent);

  return {
    title,
    content,
    metadata: {
      type: 'note', // Use an existing ContentType or extend types
      sourceUrl: validatedUrl,
    },
    embedText: `${title}\n\n${content.slice(0, 3000)}`,
  };
}

Security rules (non-negotiable):

Always use validateUrl() before fetching any URL
Always use sanitizeHtml() on external content
Never use eval(), Function(), or vm
Never log secrets

Create the agent tool

Create plugins/my-plugin/src/tool.ts — defines the tool the LLM agent can call:

import { Type, type Static } from '@mariozechner/pi-ai';
import type { AgentTool } from '@mariozechner/pi-agent-core';
import { v4 as uuidv4 } from 'uuid';
import type { NoteMetadata } from '@echos/shared';
import type { PluginContext } from '@echos/core';
import { categorizeContent, type ProcessingMode } from '@echos/core';
import { processMyContent } from './processor.js';

const schema = Type.Object({
  url: Type.String({ description: 'URL to process' }),
  tags: Type.Optional(Type.Array(Type.String(), { description: 'Tags' })),
  category: Type.Optional(Type.String({ description: 'Category' })),
  autoCategorize: Type.Optional(
    Type.Boolean({
      description: 'Automatically categorize using AI (default: false)',
      default: false,
    }),
  ),
  processingMode: Type.Optional(
    Type.Union([Type.Literal('lightweight'), Type.Literal('full')], {
      description: 'AI processing mode: "lightweight" (category+tags) or "full" (includes summary, gist, key points). Only used if autoCategorize is true.',
      default: 'full',
    }),
  ),
});

type Params = Static<typeof schema>;

export function createMyTool(
  context: PluginContext,
): AgentTool<typeof schema> {
  return {
    name: 'save_my_content',
    label: 'Save My Content',
    description: 'Describe what this tool does — the agent reads this to decide when to use it. Optionally auto-categorize with AI.',
    parameters: schema,
    execute: async (_toolCallId, params: Params, _signal, onUpdate) => {
      onUpdate?.({
        content: [{ type: 'text', text: `Processing ${params.url}...` }],
        details: { phase: 'fetching' },
      });

      const processed = await processMyContent(params.url, context.logger);

      const now = new Date().toISOString();
      const id = uuidv4();

      let category = params.category ?? 'uncategorized';
      let tags = params.tags ?? [];
      let gist: string | undefined;

      // Auto-categorize if requested and API key available
      if (params.autoCategorize && context.config.anthropicApiKey) {
        onUpdate?.({
          content: [{ type: 'text', text: 'Categorizing content with AI...' }],
          details: { phase: 'categorizing' },
        });

        try {
          const mode: ProcessingMode = params.processingMode ?? 'full';
          const result = await categorizeContent(
            processed.title,
            processed.content,
            mode,
            context.config.anthropicApiKey as string,
            context.logger,
            (message) => onUpdate?.({ content: [{ type: 'text', text: message }], details: { phase: 'categorizing' } }),
          );

          category = result.category;
          tags = result.tags;

          if ('gist' in result) {
            gist = result.gist;
          }

          context.logger.info(
            { category, tags, mode },
            'Content auto-categorized',
          );
        } catch (error) {
          context.logger.error({ error }, 'Auto-categorization failed, using defaults');
        }
      }

      const metadata: NoteMetadata = {
        id,
        type: 'note',
        title: processed.title,
        created: now,
        updated: now,
        tags,
        links: [],
        category,
        sourceUrl: params.url,
      };
      if (gist) metadata.gist = gist;

      // Save to all three storage layers
      const filePath = context.markdown.save(metadata, processed.content);
      context.sqlite.upsertNote(metadata, processed.content, filePath);

      if (processed.embedText) {
        try {
          const vector = await context.generateEmbedding(processed.embedText);
          await context.vectorDb.upsert({
            id,
            text: processed.embedText,
            vector,
            type: metadata.type,
            title: processed.title,
          });
        } catch {
          // Embedding failure is non-fatal
        }
      }

      return {
        content: [
          {
            type: 'text' as const,
            text: `Saved "${processed.title}" (id: ${id})\nCategory: ${category}\nTags: [${tags.join(', ')}]${gist ? `\nGist: ${gist}` : ''}`,
          },
        ],
        details: { id, filePath, title: processed.title, category, tags },
      };
    },
  };
}

New in this example: AI-powered auto-categorization support using the categorizeContent function from @echos/core. When autoCategorize=true, the plugin will automatically extract category, tags, and optionally gist/summary/key points from the content.

Export the plugin

Create plugins/my-plugin/src/index.ts:

import type { EchosPlugin, PluginContext } from '@echos/core';
import { createMyTool } from './tool.js';

const myPlugin: EchosPlugin = {
  name: 'my-plugin',
  description: 'What this plugin does',
  version: '0.1.0',

  setup(context: PluginContext) {
    return [createMyTool(context)];
  },

  // Optional: cleanup on shutdown
  // teardown() { ... },
};

export default myPlugin;

Auto-discovery

Plugins are auto-discovered at runtime — src/plugin-loader.ts scans the plugins/ directory and dynamically imports any @echos/plugin-<dirname> package. No manual import or registration in src/index.ts is needed.

Wire up the workspace

Add the path mapping to root tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@echos/plugin-my-plugin": ["./plugins/my-plugin/src/index.ts"]
    }
  }
}

Install dependencies:

pnpm install

Build and verify:

pnpm -r build
pnpm test

PluginContext API

Every plugin receives a PluginContext with:

Property	Type	Description
`sqlite`	`SqliteStorage`	Metadata DB (upsert, query, FTS5 search)
`markdown`	`MarkdownStorage`	Markdown file storage (save, read, delete)
`vectorDb`	`VectorStorage`	Vector embeddings (upsert, search)
`generateEmbedding`	`(text: string) => Promise<number[]>`	Generate embedding vectors
`logger`	`Logger` (Pino)	Structured logger
`config`	`Record<string, unknown>`	App config (API keys, etc.)

AI Categorization

Plugins can use the built-in categorization service from @echos/core:

import { categorizeContent, type ProcessingMode } from '@echos/core';

// Lightweight mode: category + tags only
const result = await categorizeContent(
  title,
  content,
  'lightweight',
  context.config.anthropicApiKey as string,
  context.logger,
  // Optional: receive progressive updates as the LLM streams its response
  (message) => onUpdate?.({ content: [{ type: 'text', text: message }], details: { phase: 'categorizing' } }),
);
// result: { category: string, tags: string[] }

// Full mode: includes gist, summary, key points
const fullResult = await categorizeContent(
  title,
  content,
  'full',
  context.config.anthropicApiKey as string,
  context.logger,
  (message) => onUpdate?.({ content: [{ type: 'text', text: message }], details: { phase: 'categorizing' } }),
);
// fullResult: { category, tags, gist, summary, keyPoints }

The categorization service:

Uses streamSimple + parseStreamingJson to stream the LLM response progressively
Fires onProgress as fields resolve: category → tags → gist (full mode)
Handles errors with safe defaults (fallback to ‘uncategorized’)
Respects content length limits (5000 chars for lightweight, 10000 for full)
Is safe to call without onProgress — callers that don’t need streaming omit the last argument

See Categorization for detailed documentation.

Existing plugins

Plugin	Package	Description
YouTube	`@echos/plugin-youtube`	Transcript extraction + Whisper fallback
Article	`@echos/plugin-article`	Web article extraction via Readability + DOMPurify
Twitter	`@echos/plugin-twitter`	Tweet/thread extraction via FxTwitter API
Image	`@echos/plugin-image`	Image storage with metadata extraction (Sharp)
Resurface	`@echos/plugin-resurface`	Knowledge resurfacing via spaced repetition and on-this-day discovery
Journal	`@echos/plugin-journal`	Dedicated journaling, AI reflection, and daily prompts
PDF	`@echos/plugin-pdf`	PDF text extraction via pdf-parse
Audio	`@echos/plugin-audio`	Podcast/audio transcription via OpenAI Whisper
RSS Feeds	`@echos/plugin-rss`	Automated RSS/Atom feed subscription and article ingestion

Twitter Plugin

The Twitter plugin (@echos/plugin-twitter) provides the save_tweet tool for saving tweets and threads from Twitter/X. Features:

Save individual tweets with full metadata (text, author, engagement stats, media URLs)
Automatic thread unrolling — reply chains by the same author are merged into a clean article
Quote tweet extraction
Media URLs referenced as markdown links (images and videos)
Optional AI categorization for automatic tagging
No API key required — uses the free FxTwitter API (api.fxtwitter.com)

Supported URL formats:

twitter.com/<user>/status/<id>
x.com/<user>/status/<id>
mobile.twitter.com/<user>/status/<id>
fxtwitter.com/<user>/status/<id>
vxtwitter.com/<user>/status/<id>
All formats support query parameters (?s=20, ?t=...)

Tool: save_tweet

{
  url: string;              // Twitter/X URL (required)
  tags?: string[];          // Array of tags
  category?: string;        // Category (default: "tweets")
  autoCategorize?: boolean; // Use AI to categorize (default: true)
  processingMode?: 'lightweight' | 'full'; // AI processing mode
}

Thread unrolling:

Walks up the reply chain via replying_to_status to find earlier tweets by the same author
Stops when a different author is reached or the chain exceeds 25 tweets
Merges thread tweets into a clean article format, stripping self-reply @mentions
Single tweets (no thread) are saved in blockquote format with engagement stats

Image Plugin

The image plugin (@echos/plugin-image) provides the save_image tool for storing and organizing images in the knowledge base. Features:

Download images from URLs or accept base64 data
Extract metadata: dimensions, format, file size, EXIF
Store original files in knowledge/image/{category}/
Create searchable markdown notes with image references
Optional AI categorization for automatic tagging

Tool: save_image

{
  imageUrl?: string;        // URL to download image from
  imageData?: string;       // Base64-encoded image data
  title?: string;           // Image title
  caption?: string;         // Description or context
  tags?: string[];          // Array of tags
  category?: string;        // Category (default: "photos")
  autoCategorize?: boolean; // Use AI to categorize (default: false)
  processingMode?: 'lightweight' | 'full'; // AI processing mode
}

Supported formats:

JPEG, PNG, GIF, WebP, AVIF, TIFF, BMP
Maximum size: 20MB

Processor (processImage):

Validates image format and size
Extracts metadata using Sharp library
Generates content-based filename hash
Returns structured metadata and buffer

Storage:

Original file: knowledge/image/{category}/{hash}.{ext}
Markdown note: knowledge/note/{category}/{date}-{slug}.md
Embedded reference: ![title](../../image/{category}/{filename})

Telegram Integration:

Automatic photo handler via bot.on('message:photo')
Downloads from Telegram API
Passes URL to save_image tool
Supports captions for context

See Images for complete documentation on image handling.

Resurface Plugin

The resurface plugin (@echos/plugin-resurface) brings forgotten knowledge back to the surface through spaced repetition and serendipitous discovery. It provides a get_resurfaced agent tool and a daily scheduled job that broadcasts notes via Telegram. Features:

Three resurfacing strategies:
- forgotten — notes you haven’t seen in 7+ days, oldest first (classic spaced repetition)
- on_this_day — notes created on the same calendar date in a prior year
- mix (default) — blend of both for maximum serendipity
- random — random sampling of un-recently-surfaced notes (supported by both the get_resurfaced tool and scheduler config)
Tracks a last_surfaced timestamp per note in SQLite — never resurfaces the same note twice within 7 days
Daily broadcast job sends 2–3 notes to Telegram with emoji labels (🔮 Resurfaced, 📅 On this day, 🎲 Discovery)
On-demand access via the get_resurfaced tool

Tool: get_resurfaced

{
  mode?: 'forgotten' | 'on_this_day' | 'mix' | 'random'; // Strategy (default: 'mix')
  limit?: number;                                          // Number of notes (default: 3, max: 10)
}

Trigger phrases the agent recognises:

“surprise me”
“what did I save before?”
“on this day”
“rediscover something”
“show me something old”
“random note”

Setting up the daily job: Tell the agent:

“Schedule a daily knowledge resurfacing at 9am.”

The agent will create a resurface schedule with cron 0 9 * * *. You can customize it:

Schedule a daily resurface at 7am, on_this_day mode only.
Schedule a weekly knowledge rediscovery every Sunday at 10am, 5 notes.

Scheduler config options:

Key	Type	Default	Description
`mode`	`'forgotten' \| 'on_this_day' \| 'random' \| 'mix'`	`'mix'`	Resurfacing strategy
`limit`	number	`3`	Number of notes to broadcast (max 10)

PDF Plugin

The PDF plugin (@echos/plugin-pdf) provides the save_pdf tool for extracting and saving text from PDF documents. Features:

Download PDFs from public http(s) URLs and extract text via pdf-parse (pure JS, no native deps)
Preserves page count in the note header/body; stores author and source URL in frontmatter metadata (when available)
Enforces a 10 MiB PDF download size limit; larger binaries are rejected with a clear error
Truncates oversized content gracefully (max 500 000 chars), appending [content truncated due to size limit] and marking the “Extracted characters” field as (truncated)
Fails clearly on password-protected or corrupt PDFs
Optional AI categorization for automatic tagging
URL validation via validateUrl() (SSRF protection: only public http(s) URLs; private/localhost/internal hosts are blocked)

Tool: save_pdf

{
  url: string;              // PDF URL (required)
  title?: string;           // Override title (defaults to PDF metadata or filename)
  tags?: string[];          // Tags to apply
  categorize?: boolean;     // Use AI to categorize (default: true)
}

Metadata in saved note:

**Source:** — source URL
**Pages:** — page count
**Extracted characters:** — character count (with truncation notice if applicable)
**Author:** — if present in PDF metadata

Audio / Podcast Plugin

The audio plugin (@echos/plugin-audio) provides the save_audio tool for transcribing podcast episodes and audio files via OpenAI Whisper and saving the transcript as a searchable knowledge note. Requires OPENAI_API_KEY — Whisper is an OpenAI API service. The plugin fails gracefully with a clear message if the key is absent. Features:

Downloads audio from public http(s) URLs and transcribes via whisper-1
Supports: .mp3, .wav, .m4a, .ogg, .webm, .mp4, .flac
Files > 25 MB are split into 24 MB byte-range chunks and transcribed sequentially — no ffmpeg required
Probes file size with a HEAD request, then falls back to a Range: bytes=0-0 probe if Content-Length is absent
Streams downloads with a hard 25 MB cap to prevent unbounded memory usage
Saves notes with inputSource: 'voice' and type: 'note'
Optional AI categorization via Anthropic
Respects WHISPER_LANGUAGE config for language hints

Tool: save_audio

{
  url: string;              // Audio file URL (required)
  title?: string;           // Override title (defaults to filename from URL)
  tags?: string[];          // Tags to apply
  categorize?: boolean;     // Use AI to categorize (default: true)
}

Metadata in saved note:

**Source:** — source URL
**Format:** — file extension (e.g. MP3)
**File size:** — human-readable size (KB/MB)
**Duration estimate:** — estimated from file size and format bitrate
**Transcript length:** — character count

Chunking for large files: Files exceeding the Whisper 25 MB limit are automatically chunked:

A HEAD request probes Content-Length
If absent, a Range: bytes=0-0 request reads the Content-Range total size
If the total exceeds 25 MB, the file is fetched in 24 MB byte-range slices
Each slice is transcribed separately; results are joined with \n\n
If the server does not honour Range headers (returns 200 instead of 206), an informative error is returned

Example prompts:

“Save this podcast episode: [URL]”
“Transcribe and save this interview recording”
“Save the audio from this conference talk: [URL]“

Journal Plugin

The journal plugin (@echos/plugin-journal) provides a dedicated journaling experience with two agent tools and an optional daily prompt job. Features:

Dedicated journal tool for creating journal/diary entries (replaces create_note(type="journal"))
AI-powered reflect tool that synthesizes journal entries over a time period
Optional journal_prompt scheduled job for daily journaling nudges via Telegram

Tool: journal

{
  title: string;                          // Entry title (required)
  content: string;                        // Markdown content (required)
  tags?: string[];                        // Tags for categorization
  category?: string;                      // Category (e.g. "reflection", "work", "health")
  inputSource?: 'text' | 'voice';         // How the entry was captured (default: 'text')
}

All journal entries are stored with type: 'journal' and status: 'read'. After creating, the agent always calls categorize_note for automatic tagging. Tool: reflect

{
  period?: 'week' | 'month' | 'custom';   // Time period (default: 'week')
  dateFrom?: string;                       // Start date for custom range (ISO 8601)
  dateTo?: string;                         // End date for custom range (ISO 8601)
}

The reflect tool:

Fetches journal entries within the date range (up to 50 entries)
Spawns a sub-agent to synthesize patterns, mood trends, key themes, and insights
Returns a warm, structured reflection with actionable suggestions
Validates date ranges (max 365 days lookback)

Trigger phrases the agent recognises:

“reflect on my journal”
“weekly journal review”
“how has my week been?”
“mood summary”
“look back at my journaling”

Setting up the daily prompt: Tell the agent:

“Schedule a daily journal prompt at 9pm.”

The agent will create a journal_prompt schedule with cron 0 21 * * *. Scheduler config options:

Key	Type	Default	Description
`prompt`	string	Built-in journaling nudge	Custom prompt text (max 1000 chars)

RSS Feed Plugin

The RSS plugin (@echos/plugin-rss) provides the manage_feeds tool for subscribing to RSS and Atom feeds, with automatic background polling every 4 hours. Features:

Subscribe to any RSS 2.0 or Atom feed via URL
Automatic deduplication — each article is saved at most once, even if a manual refresh and a scheduled poll run concurrently (atomic guid claim before processing)
Full article extraction via @echos/plugin-article (Readability) — not just the feed summary
AI categorization applied automatically when ANTHROPIC_API_KEY or LLM_API_KEY is configured
Per-feed tags: all articles from a feed inherit its configured tags plus the rss tag
Background polling every 4 hours via a self-registering BullMQ schedule (rss-poll)
Plugin-specific SQLite database at {DB_PATH}/rss.db — separate from echos.db

Tool: manage_feeds

{
  action: 'add' | 'list' | 'remove' | 'refresh';
  url?: string;    // Feed URL (required for add/remove/refresh of a specific feed)
  name?: string;   // Display name (used with add; defaults to feed title)
  tags?: string[]; // Tags applied to all articles from this feed (used with add)
}

Actions:

Action	Description
`add`	Subscribe to a feed. Validates the URL, fetches the feed to confirm it parses, then stores it.
`list`	List all subscribed feeds with last-checked time and saved article count.
`remove`	Unsubscribe from a feed. Previously saved articles are retained.
`refresh`	Immediately fetch and save new articles. Omit `url` to refresh all feeds.

Example prompts:

“Subscribe to this RSS feed: https://example.com/feed.xml, tag it as ‘news’”
“List my RSS feed subscriptions”
“Unsubscribe from https://example.com/feed.xml”
“Refresh all my RSS feeds now”

Automatic polling: On first startup, the plugin registers a default schedule (rss-poll) with cron 0 */4 * * * (every 4 hours). The schedule is stored in SQLite and picked up by the ScheduleManager — no manual setup required. To change the poll frequency, update the schedule via the agent:

“Change the RSS poll schedule to run every 2 hours.”

Storage:

Each feed entry is stored as a note with type: article, inputSource: url, and sourceUrl pointing to the original article
Feed-specific data (subscriptions, seen guids) lives in {DB_PATH}/rss.db and is managed entirely by the plugin
Deleting a feed subscription cascades to its entry records in rss.db — no orphan rows

Getting Started

Architecture

Features

Operations

Building a Plugin

Creating a Plugin

Steps

PluginContext API

AI Categorization

Existing plugins

Twitter Plugin

Image Plugin

Resurface Plugin

PDF Plugin

Audio / Podcast Plugin

Journal Plugin

RSS Feed Plugin

​Creating a Plugin

​Steps

​PluginContext API

​AI Categorization

​Existing plugins

​Twitter Plugin

​Image Plugin

​Resurface Plugin

​PDF Plugin

​Audio / Podcast Plugin

​Journal Plugin

​RSS Feed Plugin

Creating a Plugin

Steps

PluginContext API

AI Categorization

Existing plugins

Twitter Plugin

Image Plugin

Resurface Plugin

PDF Plugin

Audio / Podcast Plugin

Journal Plugin

RSS Feed Plugin