Skip to content

fix: memories table schema migration for v0.1.x → v0.2.x upgrade path (v0.2.1)#13

Merged
tryweb merged 1 commit intomainfrom
fix/memories-schema-migration
Mar 21, 2026
Merged

fix: memories table schema migration for v0.1.x → v0.2.x upgrade path (v0.2.1)#13
tryweb merged 1 commit intomainfrom
fix/memories-schema-migration

Conversation

@tryweb
Copy link
Owner

@tryweb tryweb commented Mar 21, 2026

Problem

After upgrading from v0.1.x to v0.2.0, any existing database fails immediately with:

Schema error: No field named 'lastRecalled'. Valid fields are scope, importance, timestamp, schemaVersion, vectorDim, id, text, vector, category, embeddingModel, metadataJson.

Root Cause

v0.2.0 added three new fields to every memory record (lastRecalled, recallCount, projectCount) and updated readByScopes() to SELECT them. However, unlike the effectiveness_events table which already had ensureEventTableCompatibility() to patch missing columns on init, there was no equivalent for the memories table. Existing v0.1.x databases simply don't have those columns.

Fix

  • Add ensureMemoriesTableCompatibility() using the same addColumns() pattern as ensureEventTableCompatibility()
  • Call it from init() after the memories table is opened, before ensureIndexes()
  • New columns get CAST(0 AS BIGINT/INT) as their SQL default, so all legacy records read back with value 0
  • Add seedLegacyMemoriesTable() test helper and a new foundation test that seeds a v0.1.x-style DB (no usage tracking columns) and verifies the three fields are readable after migration

Verification

  • Foundation tests: 11/11 (new test 9 covers the migration path)
  • npm run verify: foundation 11/11, regression 18/18, retrieval 2/2

…/projectCount

Databases created with v0.1.x were missing the three new fields added in
v0.2.0 (lastRecalled, recallCount, projectCount). On the first query after
upgrading, LanceDB threw:

  Schema error: No field named 'lastRecalled'. Valid fields are scope,
  importance, timestamp, schemaVersion, vectorDim, id, text, vector,
  category, embeddingModel, metadataJson.

Root cause: ensureMemoriesTableCompatibility() was never implemented,
while the equivalent ensureEventTableCompatibility() already existed for
the effectiveness_events table.

Fix:
- Add ensureMemoriesTableCompatibility() using the same addColumns() pattern
- Call it from init() after table open, before ensureIndexes()
- Add seedLegacyMemoriesTable() test helper in test/setup.ts
- Add foundation test 'store init patches legacy memories schema...'
  that seeds a v0.1.x-style table and verifies the three columns are
  readable with value 0 after migration

Bump version to 0.2.1.
@tryweb tryweb merged commit a6f2fbb into main Mar 21, 2026
3 checks passed
@tryweb tryweb deleted the fix/memories-schema-migration branch March 21, 2026 11:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant