Plugin architecture

Shipped in v3-alpha (Beta). The @mnemosyne/plugins interface (9 builtins) lets third parties extend Mnemosyne without forking. Interfaces may still change before 3.0 stable.

The interface

interface MnemoPlugin {
  name: string;
  version: string;
  description: string;
 
  // Lifecycle
  onInit?(ctx: PluginContext): Promise<void>;
  onShutdown?(): Promise<void>;
  onHealthCheck?(): Promise<PluginHealth>;
 
  // Write-path hooks (can modify pipeline)
  onBeforeWrite?(unit: KnowledgeUnit): KnowledgeUnit | null;  // null = reject
  onAfterWrite?(unit: KnowledgeUnit): void;
 
  // Read-path hooks
  onBeforeRecall?(input: RecallInput): RecallInput;
  onAfterRecall?(hits: RecallHit[]): RecallHit[];
 
  // Event hooks (async)
  onFactCreated?(fact: MnemoFact): Promise<void>;
  onTaskCompleted?(task: MnemoTask): Promise<void>;
  onSessionCollapsed?(s: SessionCollapseSummary): Promise<void>;
  onConflictDetected?(c: FactConflict): Promise<void>;
  onWorthChanged?(memoryId: string, newWorth: number): Promise<void>;
 
  // Polling sync
  syncInterval?: number;
  sync?(): Promise<SyncResult>;
 
  // Verification (codebase-aware)
  verify?(facts: MnemoFact[]): Promise<VerificationResult[]>;
}

Built-in plugins shipped with v3

Plugin	Purpose	Direction	Trigger
`git-verifier`	Verify facts against repo state	repo → invalidate stale facts	daily cron
`outline-sync`	Import KB articles	Outline → facts	webhook + interval
`webhook-notify`	Push events to external systems	memory → HTTP	on event
`obsidian-export`	Export graph as Markdown vault	memory → .md	on demand
`claude-import`	Import from Claude’s memory	JSON → facts	on demand
`slack-events`	Record Slack messages as events	Slack → events	webhook
`github-events`	Record PR/Issue activity	GitHub → events + tasks	webhook
`calendar-sync`	Import calendar events	Google/Outlook → episodes	interval
`feedback-loop`	User feedback → memory worth	UI rating → worth update	on feedback

Sandbox

Plugins run in the same process but with constrained access:

interface PluginContext {
  // Read-only memory access (through agent RBAC)
  recall(query: string): Promise<RecallHit[]>;
  getFact(id: string): Promise<MnemoFact | null>;
 
  // Write access — rate-limited, audited
  createFact(input: CreateFactInput): Promise<MnemoFact>;
  createEvent(input: CreateEventInput): Promise<MnemoEvent>;
 
  // NO access to:
  // - Raw database connection
  // - Other workspaces
  // - Admin operations
  // - Other plugins' state
 
  // Private state — persisted in mnemo_plugin_state
  state: PluginStateStore;
  log: PluginLogger;
}

Plugin architecture

The interface

Built-in plugins shipped with v3

Sandbox

See also