### Quick Start: Basic Scheduler Setup

Source: https://github.com/usememos/memos/blob/main/internal/scheduler/README.md

Demonstrates how to initialize a new scheduler, register a job with a cron schedule, and start the scheduler. Ensure to keep the application running to allow jobs to execute.

```go
package main

import (
    "context"
    "fmt"
    "github.com/usememos/memos/internal/scheduler"
)

func main() {
    s := scheduler.New()

    s.Register(&scheduler.Job{
        Name:     "daily-cleanup",
        Schedule: "0 2 * * *", // 2 AM daily
        Handler: func(ctx context.Context) error {
            fmt.Println("Running cleanup...")
            return nil
        },
    })

    s.Start()
    defer s.Stop(context.Background())

    // Keep running...
    select {}
}
```

--------------------------------

### Start Production Preview Server

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-05-12-first-screen-lazy-heavy-deps.md

Start a production preview server to verify the network behavior of the auth/signup route in a production-like environment.

```bash
cd web && pnpm exec vite preview --host 127.0.0.1 --port 4173
```

--------------------------------

### Start Backend and Frontend Development Servers

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-05-02-transcription-settings.md

These commands start the backend server on port 8081 and the frontend development server. This setup is necessary for manual smoke testing.

```bash
go run ./cmd/memos --port 8081 &
cd web && pnpm dev
```

--------------------------------

### Install Memos Native Binary

Source: https://github.com/usememos/memos/blob/main/README.md

Installs the Memos native binary by downloading and executing an installation script. Ensure you have curl installed.

```bash
curl -fsSL https://raw.githubusercontent.com/usememos/memos/main/scripts/install.sh | sh
```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/usememos/memos/blob/main/AGENTS.md

Installs Node.js dependencies for the frontend using pnpm. Run this after cloning the repository or when frontend dependencies change.

```bash
cd web && pnpm install             # Install dependencies
```

--------------------------------

### MCP Client Configuration Example

Source: https://github.com/usememos/memos/blob/main/server/router/mcp/README.md

Example JSON configuration for connecting a Streamable HTTP MCP client to the Memos instance. Ensure to replace placeholders with your actual instance URL and personal access token.

```json
{
  "mcpServers": {
    "memos": {
      "type": "http",
      "url": "https://<your-instance>/mcp",
      "headers": {
        "Authorization": "Bearer <your-personal-access-token>"
      }
    }
  }
}
```

--------------------------------

### Verify buf Installation

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-05-02-stt-audiollm-split.md

Check if the 'buf' tool is installed and accessible in your environment. If not, follow the provided instructions to install it.

```bash
buf --version
```

--------------------------------

### Install Tiptap Packages

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-06-11-markdown-wysiwyg-editor.md

Install the necessary Tiptap packages and their peer dependencies using pnpm. Ensure no peer-dependency errors occur.

```bash
cd /Users/steven/Projects/usememos/memos/web
pnpm add @tiptap/core@3.26.0 @tiptap/pm@3.26.0 @tiptap/react@3.26.0 @tiptap/starter-kit@3.26.0 @tiptap/extension-list@3.26.0 @tiptap/extensions@3.26.0 @tiptap/suggestion@3.26.0 @tiptap/markdown@3.26.0 marked@^17.0.1
```

--------------------------------

### Start Memos Backend Dev Server

Source: https://github.com/usememos/memos/blob/main/AGENTS.md

Starts the Go backend development server on port 8081. Use this for local development and testing of backend features.

```bash
go run ./cmd/memos --port 8081    # Start backend dev server
```

--------------------------------

### Start Development Server

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-05-02-activity-calendar-time-basis.md

Launch the development server for the Memos project on a specified port. This is typically done in one terminal to allow for manual testing.

```bash
go run ./cmd/memos --port 8081
```

--------------------------------

### Start Frontend Dev Server

Source: https://github.com/usememos/memos/blob/main/AGENTS.md

Starts the frontend development server using Vite on port 3001. It proxies API requests to the backend running on port 8081.

```bash
cd web && pnpm dev                 # Dev server on :3001, proxying API to :8081
```

--------------------------------

### Start Development Server

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-05-12-placeholder-component.md

Launch the development server to manually inspect the placeholder component's behavior. Navigate to the Inbox page and verify the empty state appearance, animation, and message display.

```bash
cd web && pnpm dev
```

--------------------------------

### Build Frontend

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-05-02-stt-audiollm-split.md

Navigate to the web directory and execute the build command using pnpm. If pnpm is not installed or used, use 'npm run build'. This verifies that the frontend build process completes without TypeScript errors.

```bash
cd web && pnpm build && cd ..
```

--------------------------------

### Graceful Shutdown Example

Source: https://github.com/usememos/memos/blob/main/internal/scheduler/README.md

Demonstrates how to perform a graceful shutdown of the scheduler, giving jobs a specified time to complete.

```APIDOC
## Graceful Shutdown Example

### Description
Shows how to use `Stop` with a context to allow jobs to finish cleanly.

### Code Example
```go
// Give jobs up to 30 seconds to complete
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

if err := s.Stop(ctx); err != nil {
    log.Printf("Shutdown error: %v", err)
}
```
```

--------------------------------

### Generate Code with Buf

Source: https://github.com/usememos/memos/blob/main/proto/README.md

Run this command to generate code artifacts using buf. Ensure buf is installed and configured.

```sh
buf generate
```

--------------------------------

### ConfirmDialog Usage Example

Source: https://github.com/usememos/memos/blob/main/web/src/components/ConfirmDialog/README.md

Demonstrates how to use the ConfirmDialog component with localization and asynchronous confirmation handling. Ensure 'open' state and 'onOpenChange' are managed by the parent component.

```tsx
import {
  useTranslate
} from "@/utils/i18n";
import ConfirmDialog from "@/components/ConfirmDialog";

const t = useTranslate();

<ConfirmDialog
  open={open}
  onOpenChange={setOpen}
  title={t("memo.delete-confirm")}
  description={t("memo.delete-confirm-description")}
  confirmLabel={t("common.delete")}
  cancelLabel={t("common.cancel")}
  onConfirm={handleDelete}
  confirmVariant="destructive"
/>;
```

--------------------------------

### CSS Example: Using Primary Brand Colors

Source: https://github.com/usememos/memos/blob/main/web/src/themes/COLOR_GUIDE.md

Demonstrates how to apply primary brand colors for call-to-action buttons and active navigation items using CSS variables.

```css
/* Example usage */
.cta-button {
  background: var(--primary);
  color: var(--primary-foreground);
}
```

--------------------------------

### ConfirmDialog Usage Example

Source: https://github.com/usememos/memos/blob/main/web/src/components/ConfirmDialog/README.md

Demonstrates how to use the ConfirmDialog component in a React application, including setting its open state, providing localized labels, and handling confirmation actions.

```APIDOC
## ConfirmDialog Component Usage

### Description
This example shows how to integrate the `ConfirmDialog` component into your React application. It covers managing the dialog's visibility, providing necessary text labels through a translation hook, and defining the confirmation and cancellation logic.

### Component Signature
```tsx
<ConfirmDialog
  open={open}
  onOpenChange={setOpen}
  title={t("memo.delete-confirm")}
  description={t("memo.delete-confirm-description")}
  confirmLabel={t("common.delete")}
  cancelLabel={t("common.cancel")}
  onConfirm={handleDelete}
  confirmVariant="destructive"
/>
```

### Props
- **`open`** (boolean, Required): Controls the visibility of the dialog. Set to `true` to show, `false` to hide.
- **`onOpenChange`** ((open: boolean) => void, Required): A callback function that receives the next open state. It should be used to update the parent component's state (e.g., `setOpen`).
- **`title`** (React.ReactNode, Required): The main action summary displayed in the dialog header. Typically a localized string or React node.
- **`description`** (React.ReactNode, Optional): Additional contextual information displayed below the title. Can be a localized string or React node.
- **`confirmLabel`** (string, Required): The text for the confirmation button. Should be a short, localized string (1-2 words).
- **`cancelLabel`** (string, Required): The text for the cancel button. Should be a localized string.
- **`onConfirm`** (() => void | Promise<void>, Required): The function to execute when the user confirms the action. It can be a synchronous function or an asynchronous function (Promise). If the Promise resolves, the dialog closes. If it rejects, the dialog remains open.
- **`confirmVariant`** (string, Optional): Determines the style of the confirmation button. Acceptable values are `"default"` (default) or `"destructive"` for irreversible actions.
```

--------------------------------

### Run frontend lint and build

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-05-02-transcription-settings.md

Navigate to the web directory and run both the linting and build processes for the frontend. Expected to pass for both.

```bash
cd web && pnpm lint && pnpm build
```

--------------------------------

### Initialize and Register MCP Service

Source: https://github.com/usememos/memos/blob/main/server/router/mcp/README.md

Demonstrates how to initialize the MCP service after registering API routes and pass the Echo server instance.

```go
mcpService, err := mcp.NewMCPService(profile, echoServer)
if err != nil {
    return nil, errors.Wrap(err, "failed to create MCP service")
}
mcpService.RegisterRoutes(echoServer)
```

--------------------------------

### Launch a Memos Demo Instance

Source: https://github.com/usememos/memos/blob/main/server/router/mcp/evals/README.md

Launches a throwaway demo-mode instance of the memos server using SQLite and a temporary data directory. Ensure to specify a free port and the instance URL.

```bash
go run ./cmd/memos --demo --driver sqlite \
  --port 8099 --data "$(mktemp -d)" \
  --instance-url http://localhost:8099
```

--------------------------------

### Verify and Build Web Project

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-06-11-markdown-wysiwyg-editor.md

Run lint, test, and build commands for the web project. Monitor the gzipped size of chunks containing tiptap to ensure it stays within the specified budget.

```bash
cd /Users/steven/Projects/usememos/memos/web
pnpm lint && pnpm test && pnpm build
```

--------------------------------

### Test Attachment Endpoint

Source: https://github.com/usememos/memos/blob/main/server/router/fileserver/README.md

Example cURL command to test the attachment endpoint by providing a UID and filename.

```bash
# Test attachment
curl "http://localhost:8081/file/attachments/{uid}/file.jpg"
```

--------------------------------

### Scheduler Control

Source: https://github.com/usememos/memos/blob/main/internal/scheduler/README.md

Start the scheduler to begin executing jobs and stop it gracefully to allow running jobs to complete.

```APIDOC
## Scheduler Control

### Description
Manages the lifecycle of the scheduler.

### Methods
- **Start() error**:
  - Description: Begins executing scheduled jobs.
- **Stop(ctx context.Context) error**:
  - Description: Initiates a graceful shutdown, allowing running jobs to complete within the context's deadline.
```

--------------------------------

### Test Avatar Endpoint by Username

Source: https://github.com/usememos/memos/blob/main/server/router/fileserver/README.md

Example cURL command to test the user avatar endpoint using a username.

```bash
# Test avatar by username
curl "http://localhost:8081/file/users/steven/avatar"
```

--------------------------------

### Run Full Backend Suite

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-05-02-transcription-settings.md

Execute the full backend suite with race detection enabled to identify potential concurrency issues.

```bash
go test -race ./server/... ./internal/...
```

--------------------------------

### Send a Test Email with Memos

Source: https://github.com/usememos/memos/blob/main/internal/email/README.md

Demonstrates how to configure and send a basic test email using the Memos email package. Ensure you replace placeholder credentials with your actual email and app password.

```go
package main

import (
    "log"
    "github.com/usememos/memos/internal/email"
)

func main() {
    config := &email.Config{
        SMTPHost:     "smtp.gmail.com",
        SMTPPort:     587,
        SMTPUsername: "your-email@gmail.com",
        SMTPPassword: "your-app-password",
        FromEmail:    "your-email@gmail.com",
        FromName:     "Test",
        UseTLS:       true,
    }

    message := &email.Message{
        To:      []string{"recipient@example.com"},
        Subject: "Test Email",
        Body:    "This is a test email from Memos email plugin.",
    }

    if err := email.Send(config, message); err != nil {
        log.Fatalf("Failed to send email: %v", err)
    }

    log.Println("Email sent successfully!")
}
```

--------------------------------

### Draft PR Description

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-05-12-placeholder-component.md

Example PR description outlining the changes, out-of-scope items, and the test plan for the placeholder component.

```markdown
## Summary

- Adds a new `<Placeholder variant="empty | loading | noResults | notFound">` component that renders a hand-curated ASCII bird from a pool-shaped data file, with subtle CSS-only motion that respects `prefers-reduced-motion`.
- Replaces the single-purpose `Empty.tsx` (used in `Inboxes.tsx`) with `<Placeholder variant="empty">`.
- ASCII art is from Joan Stark's (jgs) classic collection — attribution is preserved on every piece and in a co-located `CREDITS.md`.

## Out of scope (follow-up opportunities)

- Wire `<Placeholder variant="noResults">` into the memo search results page.
- Wire `<Placeholder variant="notFound">` into the router 404 catch-all.
- Wire `<Placeholder variant="loading">` into Suspense fallbacks.
- Seed additional ASCII pieces per variant — the pool architecture supports it; just append entries to `ASCII_POOL`.

## Test plan

- [ ] `pnpm lint` clean
- [ ] `pnpm test` green (incl. new `placeholder-pool` and `placeholder-component` suites)
- [ ] `pnpm build` succeeds
- [ ] Inbox empty state shows the ASCII parrot, bobs, and renders the filter-specific message
- [ ] `prefers-reduced-motion: reduce` produces a static bird and an instantly-visible message

```

--------------------------------

### Run Full Test Suite

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-05-12-placeholder-component.md

Execute the complete test suite for the web project. Ensure all existing tests pass and new suites for `placeholder-pool` and `placeholder-component` are green.

```bash
cd web && pnpm test
```

--------------------------------

### Tag Placement: End of Content

Source: https://github.com/usememos/memos/wiki/Best-practices-to-write-a-TAG

Place tags on the last line of content for accurate recognition. This example shows tags at the very end.

```markdown
GitHub Copilot is your AI pair programmer that empowers you to complete tasks 55% faster by turning natural language prompts into coding 
suggestions.
#Mark #Utils 
```

--------------------------------

### Tag Placement: Beginning of Content

Source: https://github.com/usememos/memos/wiki/Best-practices-to-write-a-TAG

Place tags on the first line of content for accurate recognition. This example shows tags at the very beginning.

```markdown
#Mark #Website 
The place for anyone from anywhere to build anything
Whether you’re scaling your startup or just learning how to code, GitHub is your home. 
Join the world’s largest developer platform to build the innovations that empower humanity. 
Let’s build from here.
```

--------------------------------

### Initialize MCP Service

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-06-08-openapi-mcp-support.md

Initializes a new MCP service by loading OpenAPI specifications, building an operation registry, and setting up the MCP server. Ensure the OpenAPI path is correct.

```go
package mcp

import (
	"bytes"
	"context"
	"net/http"

	"github.com/labstack/echo/v5"
	sdkmcp "github.com/modelcontextprotocol/go-sdk/mcp"
	"github.com/pkg/errors"

	"github.com/usememos/memos/internal/profile"
)

type MCPService struct {
	profile          *profile.Profile
	echoServer       *echo.Echo
	adapter          *apiAdapter
	server           *sdkmcp.Server
	handler          http.Handler
	operationsByTool map[string]*registeredOperation
}

func NewMCPService(ctx context.Context, profile *profile.Profile, echoServer *echo.Echo, openAPIPath string) (*MCPService, error) {
	spec, err := loadOpenAPISpec(openAPIPath)
	if err != nil {
		return nil, err
	}
	registry, err := buildOperationRegistry(spec)
	if err != nil {
		return nil, err
	}
	tools, operationsByTool, err := buildCuratedTools(registry)
	if err != nil {
		return nil, err
	}

	sdkServer := sdkmcp.NewServer(&sdkmcp.Implementation{Name: "memos", Version: "1.0.0"}, nil)
	service := &MCPService{
		profile:          profile,
		echoServer:       echoServer,
		adapter:          newAPIAdapter(echoServer),
		server:           sdkServer,
		operationsByTool: operationsByTool,
	}
	for _, tool := range tools {
		registered := operationsByTool[tool.Name]
		sdkServer.AddTool(tool, service.handlerForOperation(registered.Operation))
	}
	service.handler = sdkmcp.NewStreamableHTTPHandler(func(*http.Request) *sdkmcp.Server {
		return sdkServer
	}, &sdkmcp.StreamableHTTPOptions{Stateless: true, JSONResponse: true})

	_ = ctx
	return service, nil
}

```

--------------------------------

### Get Attachment Blob Function

Source: https://github.com/usememos/memos/blob/main/server/router/fileserver/README.md

Retrieves the binary content of an attachment from its storage location, which could be local storage, S3, or the database.

```Go
getAttachmentBlob(attachment) ([]byte, error)
```

--------------------------------

### Convert Instance AISetting To Store (Go)

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-05-02-transcription-settings.md

Converts an instance AI setting from the API format to the store format, including transcription settings. Ensure the input `setting` is not nil.

```go
func convertInstanceAISettingToStore(setting *v1pb.InstanceSetting_AISetting) *storepb.InstanceAISetting {
	if setting == nil {
		return nil
	}

	aiSetting := &storepb.InstanceAISetting{
		Providers:     make([]*storepb.AIProviderConfig, 0, len(setting.Providers)),
		Transcription: convertTranscriptionConfigToStore(setting.GetTranscription()),
	}
	for _, provider := range setting.Providers {
		if provider == nil {
			continue
		}
		aiSetting.Providers = append(aiSetting.Providers, &storepb.AIProviderConfig{
			Id:       provider.GetId(),
			Title:    provider.GetTitle(),
			Type:     storepb.AIProviderType(provider.GetType()),
			Endpoint: provider.GetEndpoint(),
			ApiKey:   provider.GetApiKey(),
		})
	}
	return aiSetting
}
```

--------------------------------

### Example Markdown Content

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-06-11-markdown-wysiwyg-editor.md

A sample markdown string demonstrating various formatting elements like headings, bold, italics, lists, and blockquotes.

```markdown
# 日本語の見出し

これは**太字**と*斜体*のテストです。改行も確認します。

- 中文列表项
- 한국어 항목
- emoji 🎉 in a list 🚀

> 引用文です 😀
```

--------------------------------

### Verify Dependency Graph Removal

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-05-31-remove-react-use.md

Checks the dependency graph to confirm that `react-use` and `js-cookie` are no longer listed as installed packages. This is done from the `web` directory.

```bash
cd web
pnpm why react-use js-cookie
```

--------------------------------

### Run Full Go Test Suite

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-05-02-stt-audiollm-split.md

Executes the entire Go test suite for the project. Monitor for any tests that import AI-related components and ensure they are migrated if necessary.

```bash
go test ./...
```

--------------------------------

### Go Test Command for Adapter

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-06-08-openapi-mcp-support.md

Runs tests for the OpenAPI HTTP adapter implementation. Ensure all relevant tests pass before committing.

```bash
go test ./server/router/mcp/... -run 'TestBuildAPIRequest|TestExecuteOperation|TestNormalizeStructuredContent|TestNewStructuredToolResult|TestNewToolErrorResult|TestDecodeJSONValue'
```

--------------------------------

### Commit Slash Command Feature

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-06-11-markdown-wysiwyg-editor.md

Example Git commands for linting, testing, staging, and committing the new slash command feature for the WYSIWYG editor.

```bash
pnpm lint && pnpm test
git add web/src web/tests/tiptap-slash-commands.test.ts
git commit -m "feat(web): slash command popup for wysiwyg editor"
```

--------------------------------

### Get Current User Authentication Function

Source: https://github.com/usememos/memos/blob/main/server/router/fileserver/README.md

Authenticates a request by attempting to retrieve the current user via either a session cookie or a JWT token.

```Go
getCurrentUser(ctx, c) (*store.User, error)
```

--------------------------------

### Build Transcription Instructions

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-05-02-stt-audiollm-split.md

Constructs a formatted string of instructions for the AudioLLM, including a base instruction, language specification, and contextual prompt if provided. Ensures proper formatting with newlines.

```go
func buildTranscriptionInstructions(prompt, language string) string {
	parts := []string{
		"Transcribe the audio accurately. Return only the transcript text. " +
			"Do not summarize, explain, or add content that is not spoken.",
	}
	if language = strings.TrimSpace(language); language != "" {
		parts = append(parts, "The input language is "+language+".")
	}
	if prompt = strings.TrimSpace(prompt); prompt != "" {
		parts = append(parts, "Context and spelling hints:\n"+prompt)
	}
	return strings.Join(parts, "\n\n")
}
```

--------------------------------

### Create New Git Worktree and Branch

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-05-02-transcription-settings.md

Use this command to create a new git worktree and branch for the transcription settings feature, starting from the main branch.

```bash
git worktree add -b feat/transcription-settings ../memos-transcription main
cd ../memos-transcription
git cherry-pick <spec-commit-sha>   # bring the spec doc onto the new branch
```

--------------------------------

### Run Store Tests with MySQL

Source: https://github.com/usememos/memos/blob/main/store/test/README.md

Execute store tests using the `go test` command. Ensure the `DRIVER` and `DSN` environment variables are set correctly for your MySQL instance.

```bash
DRIVER=mysql DSN=root@/memos_test go test -v ./test/store/...
```

--------------------------------

### Test Operation ID to Tool Name Conversion

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-06-08-openapi-mcp-support.md

Ensures that operation IDs are correctly converted into MCP tool names. For example, 'MemoService_ListMemos' should map to 'memo_list_memos'.

```go
func TestToolNameFromOperationID(t *testing.T) {
	require.Equal(t, "memo_list_memos", toolNameFromOperationID("MemoService_ListMemos"))
	require.Equal(t, "attachment_get_attachment", toolNameFromOperationID("AttachmentService_GetAttachment"))
}
```

--------------------------------

### Build Frontend Production

Source: https://github.com/usememos/memos/blob/main/AGENTS.md

Creates a production-ready build of the frontend application. The output is optimized for performance and deployment.

```bash
cd web && pnpm build               # Production build
```

--------------------------------

### Test HTTP Range Request

Source: https://github.com/usememos/memos/blob/main/server/router/fileserver/README.md

Example cURL command to test HTTP range requests for streaming video or audio files, specifying the byte range.

```bash
# Test range request
curl -H "Range: bytes=0-999" "http://localhost:8081/file/attachments/{uid}/video.mp4"
```

--------------------------------

### Run Full Engine and Store Suite (SQLite)

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-06-15-cel-filter-surface-expansion.md

Execute the full engine and store suite tests for SQLite to verify the implementation.

```bash
go test ./internal/filter/... ./store/...
```

--------------------------------

### Build Go Project

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-05-02-activity-calendar-time-basis.md

Compile the Go project to verify changes. This command should be run after modifying the user_service_stats.go file.

```bash
go build ./server/router/api/v1/...
```

--------------------------------

### Graceful Shutdown with Context Timeout

Source: https://github.com/usememos/memos/blob/main/internal/scheduler/README.md

Use `Stop()` with a context to allow running jobs to finish cleanly. This example provides a 30-second timeout for jobs to complete.

```go
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

if err := s.Stop(ctx); err != nil {
    log.Printf("Shutdown error: %v", err)
}
```

--------------------------------

### Convert Instance AISetting From Store (Go)

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-05-02-transcription-settings.md

Converts an instance AI setting from the store format to the API format, including transcription settings. Ensure the input `setting` is not nil.

```go
func convertInstanceAISettingFromStore(setting *storepb.InstanceAISetting) *v1pb.InstanceSetting_AISetting {
	if setting == nil {
		return nil
	}

	aiSetting := &v1pb.InstanceSetting_AISetting{
		Providers:     make([]*v1pb.InstanceSetting_AIProviderConfig, 0, len(setting.Providers)),
		Transcription: convertTranscriptionConfigFromStore(setting.GetTranscription()),
	}
	for _, provider := range setting.Providers {
		if provider == nil {
			continue
		}
		apiKey := provider.GetApiKey()
		aiSetting.Providers = append(aiSetting.Providers, &v1pb.InstanceSetting_AIProviderConfig{
			Id:         provider.GetId(),
			Title:      provider.GetTitle(),
			Type:       v1pb.InstanceSetting_AIProviderType(provider.GetType()),
			Endpoint:   provider.GetEndpoint(),
			ApiKeySet:  apiKey != "",
			ApiKeyHint: maskAPIKey(apiKey),
		})
	}
	return aiSetting
}
```

--------------------------------

### Configure Email Encryption (TLS/SSL)

Source: https://github.com/usememos/memos/blob/main/internal/email/README.md

Shows how to enable TLS/SSL encryption for email sending. Use STARTTLS on port 587 for recommended encryption, or SSL/TLS on port 465 as an alternative.

```go
// STARTTLS (port 587) - Recommended
config.UseTLS = true
```

```go
// SSL/TLS (port 465)
config.UseSSL = true
```

```go
config := &email.Config{
    SMTPPort: 587,
    UseTLS:   true,
}
```

```go
config := &email.Config{
    SMTPPort: 465,
    UseSSL:   true,
}
```

--------------------------------

### Stage and Commit Changes

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/plans/2026-05-02-stt-audiollm-split.md

Add the modified proto file and its generated bindings to the staging area, then commit them with a detailed message explaining the documentation updates for the 'model' and 'prompt' fields.

```bash
git add proto/store/instance_setting.proto \
        proto/gen/store/instance_setting.pb.go \
        web/src/types/proto/store/instance_setting_pb.ts

git commit -m "$(cat <<'EOF'
docs(proto): clarify TranscriptionConfig model and prompt fields

- model: list current OpenAI (whisper-1, gpt-4o-transcribe family,
  gpt-4o-transcribe-diarize) and Gemini (2.5-flash, 2.5-pro) examples.
  The /audio/transcriptions endpoint is no longer Whisper-only.
- prompt: note that OpenAI Whisper treats it as a soft hint while
  Gemini folds it literally into the generation prompt.

Documentation-only; no field changes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```

--------------------------------

### Log Email Sending Activity and Errors

Source: https://github.com/usememos/memos/blob/main/internal/email/README.md

Logs email sending events and errors for monitoring and security purposes. This example uses the slog package for structured logging.

```go
if err := email.Send(config, message); err != nil {
    slog.Error("Email send failed",
        slog.String("recipient", message.To[0]),
        slog.Any("error", err))
}
```

--------------------------------

### Implement Rate Limiting for Email Sending

Source: https://github.com/usememos/memos/blob/main/internal/email/README.md

Prevents abuse and excessive usage by implementing rate limiting on email sending operations. This example uses the golang.org/x/time/rate package.

```go
// Example using golang.org/x/time/rate
limiter := rate.NewLimiter(rate.Every(time.Second), 10) // 10 emails per second

if !limiter.Allow() {
    return errors.New("rate limit exceeded")
}
```

--------------------------------

### Create and Send Email

Source: https://github.com/usememos/memos/blob/main/internal/email/README.md

Construct an email message with recipients, subject, and body. Use `Send` for synchronous sending or `SendAsync` for non-blocking asynchronous sending.

```go
message := &email.Message{
    To:      []string{"user@example.com"},
    Subject: "Welcome to Memos!",
    Body:    "Thanks for signing up.",
    IsHTML:  false,
}

// Synchronous send (waits for result)
err := email.Send(config, message)
if err != nil {
    log.Printf("Failed to send email: %v", err)
}

// Asynchronous send (returns immediately)
email.SendAsync(config, message)
```

--------------------------------

### Combining Multiple Scheduler Middleware

Source: https://github.com/usememos/memos/blob/main/internal/scheduler/README.md

Demonstrates how to chain multiple middleware functions like Recovery, Logging, and Timeout. The order of middleware is crucial as they are applied from left to right, with the outermost middleware wrapping the innermost.

```go
s := scheduler.New(
    scheduler.WithMiddleware(
        scheduler.Recovery(panicHandler),
        scheduler.Logging(logger),
        scheduler.Timeout(10 * time.Minute),
    ),
)
```

--------------------------------

### Bad Practice: Tag Embedded in Prose

Source: https://github.com/usememos/memos/wiki/Best-practices-to-write-a-TAG

Tags embedded within sentences or prose may not be recognized. This example shows a tag placed mid-sentence, which is not a recommended practice.

```markdown
GitHub Mobile fits your projects in your pocket, #Mark 
so you never miss a beat while on the go.
```

--------------------------------

### Scheduler Initialization

Source: https://github.com/usememos/memos/blob/main/internal/scheduler/README.md

Create a new scheduler instance with optional configurations like middleware and timezone.

```APIDOC
## New Scheduler

### Description
Creates a new scheduler instance.

### Function Signature
`New(opts ...Option) *Scheduler`

### Options
- `WithTimezone(tz string) Option`: Sets the default timezone for jobs.
- `WithMiddleware(mw ...Middleware) Option`: Adds middleware to the scheduler.
```

--------------------------------

### Incorrect Color Pairing CSS

Source: https://github.com/usememos/memos/blob/main/web/src/themes/COLOR_GUIDE.md

Avoid pairing background and foreground colors that result in poor contrast. This example shows an incorrect pairing that can make text difficult to read.

```css
/* Incorrect - poor contrast */
background: var(--primary);
color: var(--foreground);
```

--------------------------------

### Manual Check of a Single Tool Call

Source: https://github.com/usememos/memos/blob/main/server/router/mcp/evals/README.md

Performs a manual check of a single tool call to the MCP endpoint. This example demonstrates calling the 'memo_list_memos' tool with a filter argument.

```bash
curl -s -X POST http://localhost:8099/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer memos_pat_demo' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"memo_list_memos","arguments":{"filter":"pinned == true"}}}'
```

--------------------------------

### Frontend Development Server Command

Source: https://github.com/usememos/memos/blob/main/docs/superpowers/specs/2026-05-02-transcription-settings-design.md

Instructions for running the frontend development server. Used for manual verification of transcription settings and editor button states.

```bash
- Frontend: manual verification via the dev server (`pnpm dev` in `web/`) — load Settings, add a provider, configure transcription, verify the home editor's record button enables/disables based on `provider_id`. No new component tests required (existing AISection has none).
```