MT-Mint
e338fa90d6
移除 thread_memory 对 memory_md/Markdown 解析的运行时依赖，仅保留 memory_json 读写路径。\n同步更新 SQLite/MySQL 存储实现与测试基线，并补充迁移文档的最终状态说明。
66 lines
1.9 KiB
Markdown
66 lines
1.9 KiB
Markdown
# Thread Memory Storage Migration: `memory_md` -> `memory_json`
|
|
|
|
## Summary
|
|
|
|
Per-thread memory now uses `thread_memory.memory_json` as the primary storage format.
|
|
|
|
- New writes persist structured JSON into `memory_json`.
|
|
- Reads prefer `memory_json`.
|
|
- Runtime no longer depends on `memory_md`.
|
|
|
|
## Why
|
|
|
|
`memory_md` stores structured state inside Markdown fenced blocks. This is readable for humans, but costly for:
|
|
|
|
- querying and analytics
|
|
- schema evolution
|
|
- migration reliability
|
|
|
|
`memory_json` keeps the same logical payload while making storage machine-friendly.
|
|
|
|
## Runtime behavior
|
|
|
|
- Read path uses `memory_json` only.
|
|
- Write path uses `memory_json` only.
|
|
|
|
## Auto migration behavior
|
|
|
|
- SQLite: on startup, adds `memory_json` column when missing.
|
|
- MySQL: on startup, adds `memory_json` column when missing.
|
|
No destructive migration is required for existing data.
|
|
|
|
## One-shot operational backfill (legacy command)
|
|
|
|
For faster cleanup in production, run:
|
|
|
|
```bash
|
|
cd backend
|
|
UV_CACHE_DIR=/tmp/uv-cache uv run python scripts/backfill_thread_memory_json.py --dry-run
|
|
UV_CACHE_DIR=/tmp/uv-cache uv run python scripts/backfill_thread_memory_json.py
|
|
```
|
|
|
|
Current codebase keeps this command for compatibility. In fully migrated environments it returns zero legacy rows.
|
|
|
|
## Final cleanup: drop `memory_md` column
|
|
|
|
After confirming all environments are migrated, run:
|
|
|
|
```bash
|
|
cd backend
|
|
UV_CACHE_DIR=/tmp/uv-cache uv run python scripts/drop_thread_memory_md_column.py --dry-run
|
|
UV_CACHE_DIR=/tmp/uv-cache uv run python scripts/drop_thread_memory_md_column.py
|
|
```
|
|
|
|
Notes:
|
|
|
|
- SQLite migration rebuilds `thread_memory` table and preserves data.
|
|
- MySQL migration runs `ALTER TABLE ... DROP COLUMN memory_md`.
|
|
|
|
## Follow-up (optional)
|
|
|
|
After all active environments have fully migrated and no legacy rows remain:
|
|
|
|
1. backfill any remaining rows that still rely on `memory_md`
|
|
2. remove `memory_md` column from schema
|
|
3. remove Markdown parsing fallback code
|