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
Related interfaces
These capabilities connect to other system boundaries rather than replace them. Use the related pages for the rules that each integration depends on:
- AI media processing explains the detailed audio-to-text path.
- Background job scheduling explains job timing, middleware, and shutdown behavior.
- Deployment configuration and operations explains the deployment settings that control outbound access and service connections.
- Memo lifecycle and collaboration explains memo changes, comments, mentions, visibility, and inbox creation.
- MCP, RSS, and file delivery explains other ways to expose memo content to external consumers.
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
| Trigger | Consequence | Guard |
|---|---|---|
| A webhook URL resolves to a private or reserved address | The destination is rejected or the outbound request fails | URL 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 delivery | The request can be sent to an unintended internal address | The dial path resolves and checks addresses at connection time, then dials the checked address |
A whsec_ signing secret is malformed | The webhook cannot be signed or stored | Signing-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 code | The asynchronous delivery is logged as failed | The dispatcher checks both the HTTP status and the response code |
| A webhook or email asynchronous queue is full | The event is dropped instead of waiting in an unbounded queue | The bounded queue logs the drop; operators must watch service logs |
| A comment or mention references a memo the receiver cannot read | No webhook or email is sent for that event | Delivery 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 email | No message is sent | The dispatcher skips the event and logs when the instance URL is missing |
| The selected AI provider is missing or has no API key | Transcription is unavailable | Settings tie transcription to a configured provider and stored key |
| Audio is empty, too large, or has an unsupported media type | The transcription request is rejected before provider work | The AI API validates the request and supported content types |
| A scheduled handler ignores context cancellation | Graceful scheduler shutdown can exceed its stop deadline | Handlers should honor the context passed by the scheduler |
Key files
| File | Why to read it |
|---|---|
| internal/…/scheduler.go | Defines recurring job start, timing, execution, and shutdown behavior |
| internal/…/job.go | Defines the scheduler's job contract and validation rules |
| internal/…/middleware.go | Shows shared logging, timeout, and panic recovery behavior |
| core/…/runner.go | Rebuilds derived memo payload data for one-shot or scheduled full refreshes |
| server/…/memo_service_webhooks.go | Maps memo activity to access-aware webhook events and payloads |
| internal/…/validate.go | Defines webhook URL, private-destination, and signing-secret validation |
| internal/…/webhook.go | Defines asynchronous HTTP delivery, safe dialing, signatures, and response checks |
| server/…/user_service_webhooks.go | Defines user webhook ownership and management rules |
| web/…/WebhookSection.tsx | Shows the user-facing webhook list and lifecycle actions |
| web/…/CreateWebhookDialog.tsx | Shows webhook creation, editing, and signing-secret reveal behavior |
| server/…/notification_email.go | Connects inbox creation to best-effort email dispatch |
| server/…/email.go | Connects inbox events to access-aware email messages |
| internal/…/email.go | Defines asynchronous SMTP send behavior and queue limits |
| proto/…/instance_service.proto | Defines instance notification and AI settings exposed to the API |
| server/…/ai_service.go | Defines the authenticated audio transcription boundary |
| web/…/index.tsx | Shows how transcription affects the memo draft experience |