# Memos

Single-binary self-hosted memo timeline with an OpenAPI-derived MCP endpoint at /mcp.

Memos is a Go single binary for short-form notes: a chronological markdown timeline with tags, attachments, pins, comments, reactions, and selective sharing. The server exposes a REST and gRPC API and, since 2026, a curated MCP endpoint at /mcp built from the same OpenAPI spec, so an agent authenticates with an access token and drives memos in-process against the API.

- Capabilities: adaptable, operable
- Vertical: notes-knowledge
- Shape: product
- Form factor: web-app
- Execution model: deterministic
- Provenance: mixed (recorded, never ranked)
- Repo: https://github.com/usememos/memos (MIT), 62737 stars, last commit 2026-09-03
- Last activity: 2026-09-03
- Page: apps/usememos--memos.html
- JSON: apps/usememos--memos.json

## Use it when

- you want a private micro-journal an agent can post to and read back with one access token
- you want a Twitter-style work log for a small team on one container with zero telemetry

## Gotchas

- MCP tools are a curated allowlist over the API: admin, users, and webhooks stay out of reach
- MCP uses Streamable HTTP at /mcp and needs an access token from the user's settings
- Env var names are taken from usememos.com docs by the sourcing pass; re-verify against cmd/memos/main.go

## Editions

- Free: Free, open source
  - source: https://github.com/usememos/memos
  - container: docker run -d --name memos -p 5230:5230 -v ~/.memos:/var/opt/memos neosmemo/memos:stable
  - binary: https://github.com/usememos/memos/releases

## Adaptable: make it yours

Effort: config-only (7 things to edit)

No config file: the binary reads flags or MEMOS_* env vars. MEMOS_PORT and MEMOS_DATA set the listener and data directory; MEMOS_DRIVER and MEMOS_DSN move it from SQLite to MySQL or Postgres; MEMOS_MODE selects prod or dev; MEMOS_INSTANCE_URL sets the public URL. Everything else is workspace settings in the UI.

- Env vars: MEMOS_MODE, MEMOS_PORT, MEMOS_DATA, MEMOS_DRIVER, MEMOS_DSN, MEMOS_INSTANCE_URL
- Config files: docker-compose.yml
- Prompt files: none
- Accounts you'll need: none

## Operable: what an agent can drive

Operability: official. Interface: mcp at https://github.com/usememos/memos/tree/main/server/router/mcp (published by the builder, local).

### Reach (partial coverage)

- Create, update, and delete memos: reachable. catalog.go allowlist: MemoService_CreateMemo, UpdateMemo, DeleteMemo
- List and search memos: reachable. MemoService_ListMemos, GetMemo
- Attach files: reachable. AttachmentService_CreateAttachment, ListAttachments, DeleteAttachment; MemoService_SetMemoAttachments
- Comment on memos: reachable. MemoService_CreateMemoComment, ListMemoComments
- React to memos: reachable. MemoService_UpsertMemoReaction, ListMemoReactions, DeleteMemoReaction
- Link memos to each other: reachable. MemoService_SetMemoRelations, ListMemoRelations
- Tag and pin: reachable. tags are inline #hashtags in content; pinned is a memo field on UpdateMemo
- Set visibility (private, workspace, public): reachable. visibility field on the memo resource
- Memo view statistics: reachable. MemoViewService_ListMemoViews
- Users, workspace settings, webhooks, shortcuts: not reachable. not in the curated allowlist; only AuthService_GetCurrentUser is exposed

## Code stack

- Languages: Go, TypeScript
- Frameworks: Echo, gRPC-Gateway, React
- Package manager: go modules, pnpm
- Database: SQLite, MySQL, PostgreSQL
- Hosting target: docker, binary

## Evidence and confidence

- formFactor: README: self-hosted web app, Docker quick start (confidence 0.95)
- executionModel: no model in the stack (confidence 0.95)
- operability: server/router/mcp/README.md: OpenAPI-driven MCP endpoint at /mcp using the official Go SDK; catalog.go allowlist (confidence 0.95)
- effort: MEMOS_* env vars documented at usememos.com/docs; no config file (confidence 0.7)
- editions: MIT; README 'zero telemetry'; no paid edition (confidence 0.95)
- active: pushedAt 2026-09-03
- provenance: AGENTS.md at root; project from 2021 (confidence 0.4)
- reach:  (confidence 0.9)

## Open questions

- Confirm MEMOS_* names in cmd/memos/main.go (docs deploy page did not list them)
- Is the /mcp endpoint enabled by default or behind a workspace setting?

## Sources

- https://github.com/usememos/memos (sourcing:notes-knowledge:curated)
- https://github.com/usememos/memos/tree/main/server/router/mcp (analysis)