fix: add migration for memories table + document migration workflow

AGENTS.md

@@ -150,6 +150,30 @@ tests/
   integration/          ← Service tests against real DB
 ```
 
+## Database Migrations
+
+Shellgate uses **runtime migrations** — not `drizzle-kit push`.
+
+### How it works
+- `hooks.server.ts` calls `runMigrations()` on app startup
+- Migrations are SQL files in `drizzle/` generated by Drizzle Kit
+- The app blocks all requests until migrations complete
+- Migrations are tracked in a database table, only new ones run
+
+### When you change the schema
+1. Edit `src/lib/server/db/schema.ts`
+2. Run `npm run db:generate` to create a new migration file in `drizzle/`
+3. **Commit the migration file** — it must be in git for deployment
+4. The next app startup applies it automatically
+
+### Commands
+- `npm run db:generate` — generate migration from schema diff
+- `npm run db:push` — push schema directly (dev only, skips migrations)
+- `npm run db:studio` — visual DB editor
+- `npm run db:reset` — reset DB and re-run all migrations
+
+**Important:** Never use `drizzle-kit push` in production. Always generate and commit migration files.
+
 ## Code patterns
 
 - **Services** return `null` for not-found (not throw). API routes throw `error(404, ...)`.

drizzle/0008_lonely_venus.sql

@@ -0,0 +1,17 @@
+CREATE TABLE "memories" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"token_id" uuid NOT NULL,
+	"user_identifier" varchar(128),
+	"visibility" varchar(16) NOT NULL,
+	"summary" varchar(500) NOT NULL,
+	"content" text NOT NULL,
+	"metadata" jsonb DEFAULT '{}'::jsonb,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "tokens" ADD COLUMN "default_user" varchar(128);--> statement-breakpoint
+ALTER TABLE "memories" ADD CONSTRAINT "memories_token_id_tokens_id_fk" FOREIGN KEY ("token_id") REFERENCES "public"."tokens"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "idx_memories_token" ON "memories" USING btree ("token_id");--> statement-breakpoint
+CREATE INDEX "idx_memories_visibility" ON "memories" USING btree ("visibility");--> statement-breakpoint
+CREATE INDEX "idx_memories_user" ON "memories" USING btree ("user_identifier");