# Project pack: Memos @ f0ee2fd

Facts about **Memos** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v1.md). This pack is pinned to one version and never changes after publication.

> Memos is a simple, fast place to jot down notes, ideas, links and photos as a personal timeline, a bit like a private Twitter for yourself. Find things later by tag, date or search. It runs on your own computer or server, works on your phone in the browser, and can be shared with family or a small team.

## Version and source
- Repository: https://github.com/usememos/memos
- Pinned commit: `f0ee2fd4484eeab70254582218eff9b7121cc3c4`. Use exactly this version.
- Get it: `git clone https://github.com/usememos/memos memos && cd memos && git checkout f0ee2fd4484eeab70254582218eff9b7121cc3c4`
- Or download a zip: https://github.com/usememos/memos/archive/f0ee2fd4484eeab70254582218eff9b7121cc3c4.zip
- Official docs: https://usememos.com/docs
- Live demo: https://demo.usememos.com. Public demo. Don't enter anything private.
- Licence: **MIT**. Free to use, change and share, even commercially. Keep the original copyright notice.

## Running it
- Easiest: docker run -d --name memos -p 5230:5230 -v ~/.memos:/var/opt/memos neosmemo/memos:stable # then open http://localhost:5230 and create the first account
- Needs: Docker, or for development Go 1.27 + Node 22 + pnpm
- Develop: `go run ./cmd/memos --port 8081   # and in another terminal: cd web && pnpm install && pnpm dev (http://localhost:3001)`
- Test: `go test ./... && (cd web && pnpm test)`
- Check/lint: `golangci-lint run && (cd web && pnpm lint)`
- Build: `cd web && pnpm release && go build ./cmd/memos`
- Stack: go, typescript (React 19, Vite, Tailwind CSS v4, Connect RPC, Protocol Buffers). Difficulty for a non-developer with an AI: **moderate**. Styling and the built-in extension points (custom CSS/JS, webhooks, API, MCP) are easy. Code changes span a Go backend and a React frontend, and API changes need protobuf code generation.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`, `CONTEXT.md`.

## Customisation points (settings → extend → code)
- **theme-and-language** [settings]: Light/dark/paper themes and interface language. → `Settings → Preferences (theme, language; 45+ locales in web/src/locales)`
- **custom-css-js** [settings]: Restyle Memos or add small behaviours with CSS/JS without forking. → `Settings → Instance → Additional style / Additional script (admin only)`
- **webhooks** [extend]: Send every new memo to another service (Telegram, Zapier/n8n, a backup script). → `Settings → Webhooks (server/api/user_service.go)`
- **api-and-tokens** [extend]: Create memos from scripts, shortcuts, email or a voice assistant. → `Settings → Access tokens; REST/Connect API (proto/api/*.proto, OpenAPI in proto/gen/openapi.yaml)`
- **mcp** [extend]: Let an AI assistant read and write your memos directly through the Model Context Protocol. → `/mcp endpoint (server/mcp/)`
- **colours** [code]: Change the brand colours properly at the source. → `web/src/themes/default.css, default-dark.css, paper.css (see web/src/themes/COLOR_GUIDE.md)`
- **ui-pages** [code]: New views (e.g. a daily journal page) and new UI elements. → `web/src/pages/*.tsx, web/src/components/**`
- **backend-rules** [code]: New data or behaviour. Read AGENTS.md first; proto changes need `buf generate`. → `core/ (business rules), server/api/ (handlers), store/ (database + migrations for all 3 drivers)`

## Must keep working
- Existing memos, tags, attachments and links between memos.
- Login, access tokens and visibility settings (private, protected, public).
- Database migrations must be added for SQLite, MySQL and PostgreSQL and update each LATEST.sql.
- Never hand-edit generated code in proto/gen/ or web/src/types/proto/.

## Staying updatable
Settings (custom CSS/JS) and the extend level (webhooks, API, MCP) need no fork at all, so try those first. For code changes, keep them small and follow AGENTS.md so that future Memos releases merge cleanly.

## Data, costs and safety
- Personal data: **yes**. Stored in: SQLite by default, in the mounted data folder (~/.memos); MySQL/PostgreSQL optional. Back up the single data folder. Notes are often very personal; keep the instance private or behind login.
- Public memos are visible to anyone who can reach the server. Check visibility defaults before going online.
- Access tokens act like passwords. Never paste them into chats or commit them.

---

# Customising Memos

Memos has unusually good extension points. **Many adaptations need no code at all.** Always try levels 1 and 2 before forking.

## Level 1: Settings (no code)
- **Theme and language:** Settings → Preferences.
- **Custom look and behaviour:** Settings → Instance → *Additional style* (CSS) and *Additional script* (JS). These are stored in the database and survive upgrades. Good for colours, fonts, hiding elements, or a small banner.
- **Spaces and members:** share a space with family or a team.

## Level 2: Extend (no fork)
- **Webhooks** (Settings → Webhooks): Memos sends new or updated memos to a URL. Use them with n8n/Zapier/Make, a Telegram bot, or a tiny script.
- **API + access tokens** (Settings → Access tokens): create and search memos from iOS Shortcuts, Android Tasker, email-to-memo scripts, etc. API definitions are in `proto/api/*.proto`, and OpenAPI is in `proto/gen/openapi.yaml`.
- **MCP server** at `/mcp`: connect Claude, ChatGPT or another MCP-capable assistant to read and write memos with the user's access token.

## Level 3: Code
Read upstream `AGENTS.md` first. It's short and authoritative. Summary:

| Change | Where |
|---|---|
| Colours | `web/src/themes/default.css`, `default-dark.css`, `paper.css` (guide: `web/src/themes/COLOR_GUIDE.md`) |
| A new page or view | `web/src/pages/*.tsx` + `web/src/router/` |
| UI components | `web/src/components/**` |
| Text | `web/src/locales/en.json` (other locales optional) |
| Business rules | `core/` |
| API handlers | `server/api/`; public endpoints must be added to `server/api/acl_config.go` |
| Data model | `store/` + migrations for **sqlite, mysql and postgres**, updating each `LATEST.sql` |
| API shape | `proto/*.proto`, then `cd proto && buf generate` (never hand-edit generated files) |

## Running locally
- **Just use it:** `docker run -d -p 5230:5230 -v ~/.memos:/var/opt/memos neosmemo/memos:stable`
- **Develop:**
  1. Run the backend: `go run ./cmd/memos --port 8081`
  2. Run the frontend: `cd web && pnpm install && pnpm dev`
  3. Open http://localhost:3001
- **Check before finishing:** `cd web && pnpm lint && pnpm test`, and `go test ./...` for backend changes.

## Pitfalls
- A frontend-only change can't add new data fields. If the user needs a new field, consider storing it as a **tag** or in the memo text first. That's often good enough and needs no backend change.
- Migrations must exist for all three databases.
- Keep visibility rules intact. Private memos must never leak through new views or webhooks.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/memos/f0ee2fd/bespoke.yaml) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/memos/f0ee2fd/SKILL.md)