​

Creating a Plugin

​

Steps

mkdir -p plugins/my-plugin/src

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

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

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)}`,
  };
}

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 },
      };
    },
  };
}

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;

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

pnpm install

pnpm -r build
pnpm test

​

PluginContext API

​

AI Categorization

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 }

• 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

​

Existing plugins

​

Twitter Plugin

• 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)

• 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=...)

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

• 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

• 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

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

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

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

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

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

​

Resurface Plugin

• 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

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

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

“Schedule a daily knowledge resurfacing at 9am.”

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

​

PDF Plugin

• 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)

{
  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)
}

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

​

Audio / Podcast Plugin

• 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

{
  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)
}

• **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

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

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

​

Journal Plugin

• 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

{
  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')
}

{
  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)
}

• 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)

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

“Schedule a daily journal prompt at 9pm.”

​

RSS Feed Plugin

• 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

{
  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)
}

• “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”

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

• 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