Introducing a new way to review your PRs.

Read the announcement

usememos / memos

Memos is an open-source, self-hosted note-taking app that brings your everyday thoughts together in a personal timeline. Your data stays yours, and you choose what to keep private or share.

View on GitHub

25 documents · Updated Nov 20, 2026

docs / automation-and-integrations

Automation and integrations

Automation and integrations extend Memos beyond direct page requests. The system runs recurring background work, sends memo activity to external endpoints, delivers inbox events by email, and uses configured AI services to turn recorded audio into memo text. These paths connect memo state, user settings, external services, and background execution without changing the core memo model.

Integration model

Each capability starts from a Memos event or user action and crosses a clear boundary into another service. Persistent settings decide whether the boundary is active, while the related delivery path reports or logs failures without making every external system part of the main memo operation.

The main relationships are shown below.

flowchart LR
    M[Memo or inbox event] --> W[Webhook delivery]
    M --> E[Email notification]
    U[Editor audio action] --> A[AI transcription]
    J[Registered background job] --> S[Scheduler]
    S --> B[Recurring application work]
    W --> X[External HTTP endpoint]
    E --> SMTP[SMTP server]
    A --> P[Configured AI provider]

The scheduler is a reusable background capability rather than a user-facing memo schedule in the code covered here. No memo-specific schedule resource or API is present in the relevant service and schema paths, so scheduled memo work would need to be added as a job that follows the memo lifecycle rules. See Background job scheduling for the scheduler contract and Memo lifecycle and collaboration for memo state rules.

Scheduled execution

Scheduled execution is provided by the scheduler in internal/…/scheduler.go. It gives application code a way to run named handlers at recurring times, which makes it suitable for cleanup, sync, notification, or future memo automation work.

Job model

A job has a unique name, a cron expression, a handler, and optional time-zone and descriptive metadata. The scheduler accepts five-field schedules for minute-level work and six-field schedules when seconds are needed; it evaluates each job in its own configured time zone or in the scheduler default.

References: internal/…/job.go• L9-36 internal/…/parser.go• L28-38 internal/…/parser.go• L91-127

The scheduler validates the job before registration. This keeps malformed timing rules and missing handlers out of the running set. A job handler receives a context so its work can stop when the process shuts down.

Job lifecycle

The scheduler starts one recurring execution loop for each registered job. At each due time it runs the handler, then calculates the next due time instead of creating a separate persistent task record.

Middleware supplies shared behavior around every handler. The built-in patterns support panic recovery, execution logs, and time limits. Shutdown cancels job contexts and waits for running handlers until the caller's stop context ends.

References: internal/…/scheduler.go• L68-117 internal/…/scheduler.go• L120-165 internal/…/scheduler.go• L167-201 internal/…/middleware.go• L11-23 internal/…/middleware.go• L26-93

Memo payload rebuild

The memo payload rebuild is a one-shot background operation that refreshes derived memo data from Markdown content. It processes memos in bounded batches and updates each successful memo, so a full rebuild does not require all memo records to stay in memory at once. This operation is reusable by a scheduled job or an administrative action; it does not define its own schedule.

References: core/…/runner.go• L14-27 core/…/runner.go• L28-71 core/…/runner.go• L74-87

Webhook delivery

Webhooks let a user send memo activity to an external HTTP service. A webhook is a user-owned destination with a URL and optional signing secret; the settings API controls its life cycle, while memo operations select the activity type and dispatch the event.

Memo event delivery

Memo creation, update, deletion, and comment creation produce distinct activity events. Mention and comment inbox creation remain separate from webhook delivery, which allows an external consumer to react to memo changes even when the user does not use email notifications.

The event path is asynchronous so the memo request does not wait for the external service response.

sequenceDiagram
    participant M as Memo operation
    participant V as API service
    participant Q as Webhook queue
    participant H as External endpoint
    M->>V: Create, update, delete, or comment
    V->>Q: Queue activity payload
    V-->>M: Continue the memo operation
    Q->>H: POST JSON event
    H-->>Q: HTTP response

The payload identifies the activity and creator and includes the memo that caused it. The comment event is sent to webhooks owned by the related memo creator only after the service confirms that receiver can read both the comment and its related memo. The payload is prepared with the receiver's access context so the external event follows the same visibility boundary. Deletion follows the current read boundary too: a memo that the webhook owner can no longer read is not sent, even when that owner still has authority to delete it.

References: server/…/memo_service_webhooks.go• L18-31 server/…/memo_service_webhooks.go• L33-84 server/…/memo_service_webhooks.go• L86-129 server/…/memo_delete_webhook_test.go• L22-117 server/…/memo_service.go• L181-202 server/…/memo_update_helpers.go• L58-73 server/…/memo_service_comments.go• L121-125

Endpoint contract

Webhook URLs must use HTTP or HTTPS and are checked before storage. Outbound delivery also blocks reserved and private destinations by default, which protects the server from using webhooks to reach internal services. A deployment can allow only named hostnames, IP addresses, or CIDR ranges when local targets are required; a deprecated blanket override can still disable this protection.

The outbound client resolves the destination again when it connects and dials the checked address. This keeps a later DNS change from sending a webhook to a private or reserved address. Delivery has a time limit and uses a bounded asynchronous queue, so the memo request does not wait for the endpoint.

When a signing secret exists, Memos adds Standard Webhooks style identifiers, a timestamp, and an HMAC-SHA256 signature. A whsec_ secret is decoded before signing and is rejected if its encoded key is invalid. The receiver can use these headers to verify that the body came from the configured sender. A successful delivery requires both a 2xx HTTP status and a response body with an application code of zero.

References: internal/…/validate.go• L15-31 internal/…/validate.go• L63-111 internal/…/validate.go• L176-227 internal/…/webhook.go• L24-39 internal/…/webhook.go• L56-98 internal/…/webhook.go• L113-200

Users manage their own webhook destinations through the user resource. The secret is generated by the server when omitted, is not returned in normal webhook responses, and has a separate owner-only read path. The settings UI lists destinations and supports create, edit, delete, and controlled secret reveal.

References: proto/…/user_service.proto• L697-727 proto/…/user_service.proto• L730-784 server/…/user_service_webhooks.go• L21-107 server/…/user_service_webhooks.go• L110-207 server/…/user_service_webhooks.go• L209-300 web/…/WebhookSection.tsx• L15-144 web/…/CreateWebhookDialog.tsx• L29-55 web/…/CreateWebhookDialog.tsx• L81-110 web/…/CreateWebhookDialog.tsx• L122-170 web/…/CreateWebhookDialog.tsx• L188-214

Email notifications

Email notifications turn selected inbox events into direct messages for the affected user. The instance notification setting enables the feature and supplies SMTP details, while the memo event path creates the inbox item that acts as the source for the email.

Inbox event delivery

Memos currently builds email messages for memo comments and user mentions. It checks the receiver's address, the instance URL, and the receiver's access to the referenced memo before it sends a message with a link back to Memos. For comment-related notices, that access check covers both the comment and its related memo so the email does not reveal a conversation the receiver cannot read.

Comment and mention creation follow the same relationship: first persist an unread inbox item, then attempt email delivery as a best-effort side effect. This preserves the in-app notification even when SMTP is unavailable.

References: server/…/notification_email.go• L11-27 server/…/memo_service_comments.go• L102-119 server/…/memo_mention_helpers.go• L91-145 server/…/email.go• L39-96 server/…/email.go• L136-218

SMTP transport

The instance can enable email and set an SMTP host, port, sender address, optional sender name, reply-to address, and TLS or SSL mode. The settings page also provides a test message so an operator can check the transport before relying on event delivery.

References: proto/…/instance_service.proto• L283-300 proto/…/instance_service.proto• L393-400 web/…/NotificationSection.tsx• L117-171

Notification messages use asynchronous email sending. The bounded queue keeps SMTP latency out of the event path, but a full queue or a send failure is logged rather than returned to the original memo request.

References: internal/…/email.go• L9-35 internal/…/email.go• L38-60 server/…/email.go• L88-96

AI-assisted media processing

AI-assisted media processing adds speech-to-text to the memo editor. The editor records or receives audio, sends the bytes to the authenticated AI service, and inserts returned text into the draft; it does not save the audio as a memo unless the transcription path fails or the user chooses attachment mode.

Provider model

AI providers are configured at the instance level. Each provider has a type, endpoint, and protected API key, while the transcription setting selects one provider and can add a model, language hint, and vocabulary prompt. An empty provider selection disables transcription.

The web settings support OpenAI and Gemini provider types. The server resolves the selected provider at request time, so a missing provider or key stops the request before it sends media to an external service.

References: proto/…/instance_service.proto• L302-350 web/…/AISection.tsx• L104-155 web/…/AISection.tsx• L162-224 server/…/ai_service.go• L82-105

Audio transcription

The transcription flow accepts inline audio bytes and a file name and media type. The API checks authentication, size, and supported audio or video types before it selects the configured provider. OpenAI-compatible providers use a speech-to-text endpoint. Gemini uses an audio-capable model with instructions that request transcript text only.

sequenceDiagram
    participant E as Memo editor
    participant A as AI API
    participant C as Provider config
    participant P as AI provider
    participant D as Draft editor
    E->>A: Send recorded audio bytes
    A->>C: Resolve provider and transcription rules
    A->>P: Submit audio with model hints
    P-->>A: Return transcript
    A-->>E: Return text
    E->>D: Insert text into draft

The editor enables the transcription action only when the selected provider has a stored key. An empty or failed result leaves the recording available as an attachment and shows an error to the user. See AI media processing for provider selection, audio limits, failure handling, and media-derived content details.

References: proto/…/ai_service.proto• L11-45 server/…/ai_service.go• L47-120 web/…/transcriptionService.ts• L5-22 web/…/index.tsx• L71-77 web/…/index.tsx• L136-164

These capabilities connect to other system boundaries rather than replace them. Use the related pages for the rules that each integration depends on:

Change checklist

When these files or sections are changed, remember to consider these:

  • When memo create, update, delete, or comment flows change, preserve the matching webhook activity type and the point where asynchronous delivery starts.
  • When memo visibility or comment relation rules change, check webhook payload preparation and email eligibility for every referenced memo.
  • When inbox message types or memo visibility rules change, check both in-app notification conversion and email message eligibility.
  • When notification or AI setting schemas change, update the settings UI and the server-side validation and provider resolution together.
  • When webhook signing or destination rules change, keep URL validation, outbound dial checks, and receiver-side signature expectations aligned.
  • When a scheduled job is added, changed, or removed, review its time zone, shutdown behavior, and whether its memo mutations obey the memo lifecycle contract.
  • When the memo payload rebuild moves or its derived fields change, keep the memo create, update, import, and full-rebuild paths aligned.

Important failure modes

TriggerConsequenceGuard
A webhook URL resolves to a private or reserved addressThe destination is rejected or the outbound request failsURL validation and the safe dial path block private destinations by default; an explicit hostname, IP, or CIDR allowlist is required for selected local targets
A destination changes its DNS answer between validation and deliveryThe request can be sent to an unintended internal addressThe dial path resolves and checks addresses at connection time, then dials the checked address
A whsec_ signing secret is malformedThe webhook cannot be signed or storedSigning-secret validation requires printable characters and valid base64 for the whsec_ form
A webhook receiver returns a non-2xx status or a non-zero application codeThe asynchronous delivery is logged as failedThe dispatcher checks both the HTTP status and the response code
A webhook or email asynchronous queue is fullThe event is dropped instead of waiting in an unbounded queueThe bounded queue logs the drop; operators must watch service logs
A comment or mention references a memo the receiver cannot readNo webhook or email is sent for that eventDelivery checks access to every memo needed for the event and prepares the webhook view as the receiver
Email notifications are enabled without a usable instance URL or receiver emailNo message is sentThe dispatcher skips the event and logs when the instance URL is missing
The selected AI provider is missing or has no API keyTranscription is unavailableSettings tie transcription to a configured provider and stored key
Audio is empty, too large, or has an unsupported media typeThe transcription request is rejected before provider workThe AI API validates the request and supported content types
A scheduled handler ignores context cancellationGraceful scheduler shutdown can exceed its stop deadlineHandlers should honor the context passed by the scheduler

Key files

FileWhy to read it
internal/…/scheduler.goDefines recurring job start, timing, execution, and shutdown behavior
internal/…/job.goDefines the scheduler's job contract and validation rules
internal/…/middleware.goShows shared logging, timeout, and panic recovery behavior
core/…/runner.goRebuilds derived memo payload data for one-shot or scheduled full refreshes
server/…/memo_service_webhooks.goMaps memo activity to access-aware webhook events and payloads
internal/…/validate.goDefines webhook URL, private-destination, and signing-secret validation
internal/…/webhook.goDefines asynchronous HTTP delivery, safe dialing, signatures, and response checks
server/…/user_service_webhooks.goDefines user webhook ownership and management rules
web/…/WebhookSection.tsxShows the user-facing webhook list and lifecycle actions
web/…/CreateWebhookDialog.tsxShows webhook creation, editing, and signing-secret reveal behavior
server/…/notification_email.goConnects inbox creation to best-effort email dispatch
server/…/email.goConnects inbox events to access-aware email messages
internal/…/email.goDefines asynchronous SMTP send behavior and queue limits
proto/…/instance_service.protoDefines instance notification and AI settings exposed to the API
server/…/ai_service.goDefines the authenticated audio transcription boundary
web/…/index.tsxShows how transcription affects the memo draft experience