Use Go 1.27.4 in CI and Docker for the standard library security fixes. Wait for a memo's queued updates to settle before a Space change refreshes all memo queries, so older reads cannot replace newer optimistic edits. Cover successful and failed queued updates and unrelated pending memos.
13 KiB
AGENTS.md
Repository instructions for AI coding agents. Keep this file short, concrete, and tied to commands that actually work in this repo. If a fact here conflicts with source files or CI config, trust the source file and update this guide.
Project Snapshot
Memos is a self-hosted note-taking app.
- Backend: Go 1.27.4, net/http, Connect RPC, gRPC-Gateway, Protocol Buffers.
- Frontend: React 19, TypeScript 7, Vite 8, Tailwind CSS v4,
@usememos/uion Base UI, React Query v5. - Storage: SQLite, MySQL, PostgreSQL.
- Generated API outputs:
proto/gen/for Go/OpenAPI,web/src/types/proto/for TypeScript.
Working Rules
- Read relevant code before editing; prefer local patterns over new abstractions.
- Keep diffs scoped. Do not do repo-wide cleanup, dependency churn, or generated-file rewrites unless the task requires it.
- Do not hand-edit generated proto outputs. Change
.protofiles, then runbuf generate. - Add migrations for all database drivers when schema changes, and update each driver's
LATEST.sql. - Add public API endpoints to
server/api/acl_config.go. - Ask before adding heavy dependencies, changing auth/token behavior, or altering Docker/release workflows.
Documentation
- ADRs and their companion glossary have been retired. Do not recreate them unless explicitly requested.
- Design documents in
docs/design/stay editable until the feature ships in a tagged release; keep a merged-but-unreleased design in step with its implementation. After release the body is frozen: record later design changes in a dated## Amendmentssection at the end, never by rewriting the body. Seedocs/design/README.md. Verify current behavior in source code and tests, not in design documents. - Brand copy (tagline, descriptions, README intro) comes verbatim from
BRAND.mdinusememos/.github. Change it there first; do not keep brand guidelines in this repo. - Keep contributor guidance in this file and package-local
README.mdordoc.gofiles current when relevant code changes.
Commands
Run from the repository root unless a command starts with cd.
# Backend
go run -buildvcs=true ./cmd/memos --port 8081 # Start backend with commit-derived CalVer
go run -buildvcs=true ./cmd/memos config plan --data DIR --config-dir DIR # Declarative configuration: also validate, apply, state
go test ./... # Run all Go tests
go test -v ./store/... # Store tests, including DB drivers via TestContainers
go test -v -race ./server/... # Server tests with race detector
go test -v -race ./internal/... # Internal package tests with race detector
go test -v -run TestFoo ./core/... # Run matching Go tests in one tree
go mod tidy -go=1.27.4 # Match CI tidy check
go fix ./... # Apply Go modernization fixes
go fix -diff ./... # Match CI modernization check
golangci-lint run # Go lint, config: .golangci.yaml (includes depguard layering rules)
golangci-lint run --fix # Auto-fix lint, including goimports
# Frontend
cd web && pnpm install # Install dependencies
cd web && pnpm dev # Dev server on :3001, proxying API to :8081 (or $DEV_PROXY_SERVER)
cd web && pnpm lint # Type check + Biome lint
cd web && pnpm test # Vitest unit tests
cd web && pnpm build # Production build
cd web && pnpm release # Build SPA into server/frontend/dist
# Protocol Buffers
cd proto && buf generate # Regenerate Go + TypeScript + OpenAPI
cd proto && buf lint # Lint proto files
cd proto && buf format -w # Format proto files
Repository Layout
Every root folder is named for what it holds. Read the folder's doc.go or README.md before adding to it.
| Path | Holds | May import |
|---|---|---|
cmd/memos/ |
Cobra/Viper CLI setup and server startup | anything |
server/ |
The HTTP process: net/http bootstrap, graceful shutdown, every transport | core, store, provider, markdown, filter, internal |
server/api/ |
Connect/gRPC-Gateway services, ACL config, SSE hub. Thin handlers; rules go to core/ |
|
server/fileserver/ |
Native HTTP file serving, thumbnails, range requests | |
server/frontend/ |
Static SPA serving; dist/ is the built SPA baked in by go:embed |
|
server/mcp/ |
Model Context Protocol server | |
server/auth/ |
JWT access tokens, refresh tokens, PAT handling | |
core/ |
Business rules with no HTTP and no SQL: access, notification, memopayload, memoexport, usagelimit, identityprovider, instancesetting, user, configuration |
store, provider, markdown, filter, internal |
store/ |
Store facade, cache, migrations, Driver interface; store/db/{sqlite,mysql,postgres}/ implement it |
provider, markdown, filter, internal |
markdown/ |
Markdown engine: parser, AST, memos syntax extensions, renderer, memo payload | proto/gen, internal |
filter/ |
CEL filter compiler: parse to IR, render to SQL per driver, filterable field schema | internal |
provider/ |
Backends configured by instance settings: ai, idp, storage |
proto/gen, internal |
internal/ |
Private plumbing with no memos vocabulary (identifier, email, webhook, ratelimit, …) |
third party only |
proto/api/, proto/store/ |
Public API and internal storage proto sources; proto/gen/ is generated |
|
web/src/ |
React SPA: connect.ts clients, auth-state.ts, hooks/, contexts/, components/, lib/, locales/, themes/ |
Layering rules, enforced by depguard in .golangci.yaml:
- Imports point downward only:
cmd→server→core→store→ {provider,markdown,filter} →internal. internal/packages import nothing from this module (exceptinternal/testutil, which may importproto/gen).- A package goes in
internal/only if it could be published as a standalone module unchanged. If it knows what a Memo, Space, or instance setting is, it is a root package. - Never create
util,common,base,helpers,misc, orpkgpackages. Name a package for the one thing it does, or put the code next to its only caller. - New business rules extracted from
server/apigo tocore/<resource>/, one package per resource.
File convention inside server/api/: <resource>_service.go holds the RPC handlers, <resource>_service_converters.go the
store↔proto conversion, and <resource>_service_<topic>.go further splits. Extend the matching file; do not add *_helpers2.go.
Identity providers and instance settings are the exception: declarative configuration files use their API messages, so their
conversion lives in core/identityprovider and core/instancesetting, and server/api keeps only response redaction.
Black-box service tests live in server/api/test/, unit tests next to the code.
Change Routing
| Change | Update | Verify |
|---|---|---|
| Go service or router behavior | Handlers under server/, rules under core/, tests near package |
go test -v -race ./server/... ./core/... |
| Store or migration behavior | store/, all three DB driver migrations, LATEST.sql |
go test -v ./store/... |
| Markdown, filter, or provider logic | markdown/, filter/, provider/ |
go test -v -race ./markdown/... ./filter/... ./provider/... |
| Internal package logic | Relevant internal/ package tests |
go test -v -race ./internal/... |
| Frontend behavior | Components/hooks/contexts under web/src/ |
cd web && pnpm lint && pnpm test |
| Frontend production output | Vite config or release-sensitive UI | cd web && pnpm build or pnpm release |
| Proto API | .proto source, generated outputs, proto/api/CHANGELOG.md for breaks |
cd proto && buf generate && buf lint |
| Public unauthenticated route | server/api/acl_config.go |
Targeted server test or manual route check |
Go Conventions
- Wrap errors with
errors.Wrap(err, "context")fromgithub.com/pkg/errors; do not usefmt.Errorf. - Return service errors with
status.Errorf(codes.X, "message"). - Keep imports grouped as stdlib, third-party, then
github.com/usememos/memos; goimports is run by golangci-lint. - Add doc comments for exported identifiers; godot enforces exported comment punctuation.
- Avoid package-level mutable state unless the surrounding package already uses that pattern.
Frontend Conventions
- Use
@/for absolute imports. - Follow Biome formatting: 2-space indent, double quotes, semicolons, 140-character line width.
- Put server data in React Query hooks under
web/src/hooks/; keep UI-only state in contexts or component state. - Show, edit and compose memos through
web/src/components/MemoEditor(a name or draft seed plus a mode); see itsREADME.md. - Keep generated proto TypeScript under
web/src/types/proto/out of manual edits and Biome rewrites. - UI work reads
web/node_modules/@usememos/ui/llms.txtfirst:@usememos/uiis the design system (tokens, type classes, components). Controls come from the package; build a part it lacks on Base UI as itscustom-components.mddescribes. - Use a package component when one fits (
Button,Link,Spinner,Badge). Its class functions (buttonClasses(),menuClasses(),badgeClasses()) are for elements it can't render, such as a router link or a Base UI trigger. - Action menus use
md, including custom rows styled withmenuClasses(). Compact three-dot trigger buttons keepsm. - Field text follows its component size on every device; do not add touch-specific font sizing.
- Style with Tailwind CSS v4 and the package's
mu-utilities (bg-mu-surface,text-mu-text-secondary,rounded-mu-md), text with its type classes (mu-caption,mu-body,mu-label,mu-title), andcn()for class merging. No Tailwind text sizes or old color names (muted-foreground,destructive,popover). The exceptions are the brand wordmark and emoji glyphs, whose font size is their icon box (SpaceIcon,SpaceMark,MemoViewIcon,CustomIconPicker,ReactionSelector). - Custom controls using
mu-focusmust reserve a real 1px border (transparent for borderless controls). - Focus shows through
mu-focus. Never addring-*orfocus-visible:ring-*, and never pairmu-focuswithoutline-none, which overrides it. Visually hidden text usesmu-visually-hidden; a control that appears on focus keeps Tailwind'ssr-only focus-visible:not-sr-onlypair. - Report failures with
showErrorToastfromweb/src/lib/toast.ts. A form's own validation errors go under the field (Field.Error, kept inuseFieldErrors), not in a toast. - Every new key in
web/src/locales/en.jsonis translated into all locales;tests/locale-resources.test.tsfails otherwise. A plural message is stored askey_one,key_other, … and looked up by its base key withcount. - Lucide icons outside a package control take a size class that sets box and stroke together:
mu-icon-xs(12px),mu-icon-sm(14px) ormu-icon(16px). No Tailwind sizes on 12–16px icons and nostrokeWidth.
Database And Proto Rules
- Schema changes require SQLite, MySQL, and PostgreSQL migrations plus
LATEST.sqlupdates. - Fresh-install SQL and incremental migrations must stay equivalent.
- Proto field changes must preserve compatibility unless the task explicitly allows a breaking API change. Record every
allowed break in
proto/api/CHANGELOG.md; compatibility is checked during review. - Regenerate after proto edits and include both Go/OpenAPI and TypeScript generated outputs.
Verification Policy
- Run the narrowest relevant checks while iterating.
- Before finishing, run the checks that match the changed surface from "Change Routing".
- For docs-only changes,
git diff --checkis sufficient unless the docs include runnable examples that should be tested. - If a required check cannot run locally, report the reason and the exact command that remains.
CI Reference
-
Releases are cut by pushing a
YY.MM.N[-rc.K]tag. To cut, promote, or check a release, follow.agents/skills/release/SKILL.md. -
Development builds use the HEAD committer date in UTC as
YY.MM.D-dev.<sha7>; release builds inject the CalVer tag. -
go buildembeds Git metadata automatically;go runneeds-buildvcs=true. Builds without Git metadata must injectgithub.com/usememos/memos/internal/version.Versionthrough-ldflags. -
Docker excludes
.git; pass--build-arg VERSION="$(bash scripts/release_version.sh development-version)"and--build-arg COMMIT="$(git rev-parse HEAD)"when building locally (build frontend assets first). -
Workflows install toolchains through
.github/actions/setup-go(Go version fromgo.mod) and.github/actions/setup-web(pnpm fromweb/package.json, Node 24,pnpm install); change versions there, not per workflow. -
Backend CI: Go 1.27.4,
go mod tidy,go fix -diff ./..., golangci-lint v2.14.0 (including goimports), test groupsstore,server,internal,other(cmd,core,markdown,filter,provider,proto). -
Frontend CI: Node 24, pnpm 11.0.1,
pnpm lint,pnpm test,pnpm build. -
Proto CI:
buf lintandbuf formatcheck. -
Docker:
scripts/Dockerfile, Alpine 3.21 runtime, non-root user, port 5230, multi-arch amd64/arm64/arm/v7.