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

overview

Knowledge Base updated: 2026-11-19

Memos knowledge base

Memos is a self-hosted, Go-backed note system with a React web client. The server exposes protobuf-defined APIs alongside frontend, file, RSS, and MCP delivery routes.

Persistent state is managed through the store abstraction and database migrations; attachments use pluggable object storage. Memo content, access control, spaces, identities, and configuration are shared concerns across API, server, and web layers.

The web client provides memo workflows, settings and administration, and specialized calendar and map views. Deployment behavior is controlled through server configuration, containers, migrations, and declarative configuration flows.

flowchart LR
  Browser[React web client] --> Server[Go server runtime]
  Server --> API[Connect / protobuf APIs]
  Server --> Web[Static frontend delivery]
  Server --> Files[Attachment file delivery]
  Server --> Alt[MCP and RSS endpoints]
  API --> Auth[Identity and access control]
  API --> Memo[Memo lifecycle]
  API --> Store[Store abstraction]
  Memo --> Content[Markdown and payload processing]
  Memo --> Spaces[Spaces and membership]
  Store --> DB[(SQLite / MySQL / PostgreSQL)]
  Store --> Object[Object storage]
  Server --> Config[Runtime and declarative configuration]
  Config --> Ops[Deployment and operations]
  Browser --> API

Glossary

  • Memo: the primary persisted note record, with content, visibility, relations, and associated resources.
  • Space: a hierarchical organizational scope with membership and memo behavior.
  • Memo view: a saved or configured memo-selection view exposed through user-facing APIs and pages.
  • Payload: derived memo content detected and refreshed by the payload-processing flow.
  • Declarative configuration: versioned instance-resource configuration that is planned, validated, and applied with persisted state.

Codebase-wide invariants

  • API contract changes originate in proto/…/*.proto; generated bindings under proto/gen/api/** must remain consistent with them.
  • Server handlers enforce request identity and authorization before operating on persisted resources; see server/api/** and authorization middleware patterns.
  • Persistent model changes require compatible store, driver, and migration handling; see store/** and migration files under store/db/**.
  • Web product flows consume the server API rather than directly accessing persistence; see web/src/** and server/api/**.
  • Attachment metadata and bytes are distinct concerns: attachment records are persisted through the store while bytes are handled through storage drivers; see store/** and server/**/storage/** patterns.

Routing table