用途：在 letta-cloud 仓库的 apps/core 中修改数据库 schema 或调试 Alembic 迁移时使用。前提：工作目录为 apps/core，迁移位于 apps/core/alembic，Python 运行器为 uv，辅助命令为 just ready。
快速开始：先运行 just ready 准备环境与数据库；Postgres 迁移需设置 export LETTA_PG_URI=postgresql+pg8000://postgres:postgres@localhost:5432/letta-core；修改 ORM/schema 后，用 uv run alembic revision --autogenerate -m "<short_message>" 自动生成迁移，再用 uv run alembic upgrade head 应用。
主要工作流：新增或修改列时优先改 letta/orm/... 中的 SQLAlchemy 模型，尽量复用 mixin（如 ProjectMixin），生成后检查 alembic/versions/ 下的 op.add_column / op.alter_column 是否符合预期。数据回填或一次性数据迁移需先完成 schema 变更，再新建或编辑迁移，在 upgrade() 中用 op.get_bind() 配合 SQLAlchemy Core/SQL 回填，downgrade() 保持简单可逆。修复错误迁移时，若仅 SQLite 失败（ALTER 约束限制）或误指向 SQLite，可设置 LETTA_PG_URI 改用 Postgres 重跑；逻辑错误应新建修复迁移，而非修改已应用的迁移，除非是纯本地历史且无人依赖。
SQLite 与 Postgres 切换：Alembic 依据 letta.settings.DatabaseChoice 与环境变量选择引擎；本地有状态运行由 just ready 处理基线迁移，schema 设计与类生产迁移建议用 Postgres。重置本地 Postgres 以生成干净迁移的步骤：删除 ./data/postgres、停止 ankane/pgvector 容器、运行 just start-services、进入 apps/core 设置 LETTA_PG_URI 后执行 uv run alembic upgrade head，再生成新迁移。
常见问题：自动生成提示目标数据库未更新时先执行 upgrade head；SQLite 报 ALTER CONSTRAINT 的 NotImplementedError 时改用 Postgres；自动生成缺少预期变更时检查 ORM 导入与 Base.metadata；出现意外删除或重命名时审查模型改动，必要时改用显式操作或重置本地 Postgres。更多命令与引擎差异见 references/migration-commands.md 和 references/sqlite-vs-postgres-gotchas.md。