Skip to content

v2.6.0 — native RELATE synapse graph + SurrealDB 3.2.0

Choose a tag to compare

View all tags
@acidkill acidkill released this 07 Jul 11:52
· 210 commits to main since this release
v2.6.0
b72b4c5
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

surreal-memory 2.6.0 moves the synapse graph onto native SurrealDB RELATE edges, makes SurrealDB 3.2.0 a hard requirement, and folds in the recovered maturation / semantic-discovery / recall fixes that shipped alongside it.

⚠️ This is a breaking release with an automatic, one-time data migration. Back up your surrealdb_data volume before upgrading.

⚠️ Breaking changes

  • Requires SurrealDB ≥ 3.2.0. On startup store.initialize() now hard-fails with a clear StorageVersionError and an upgrade hint when it detects an older server.
  • The synapse graph auto-migrates to native RELATE edges on first connect. The flat source_id/target_id columns become the built-in in/out edge endpoints. Existing synapse ids, fiber.synapse_ids, change_log entries and the Merkle root are preserved (verified byte-stable). The pre-migration rows are kept in a synapse_migration_backup table for rollback.

Upgrade

# 1) Back up the data volume first (the migration runs in place on first connect)
docker run --rm -v surrealdb_data:/data -v "$PWD":/backup alpine \
  tar czf /backup/surrealdb_data.backup.tgz -C /data .

# 2) Pull SurrealDB 3.2.0 and restart
docker compose -f docker-compose.surrealdb.yml pull
docker compose -f docker-compose.surrealdb.yml up -d

# 3) First app connect auto-migrates. Verify:
smem doctor                              # SurrealDB version check + overall health
smem doctor --synapse-migration status   # inspect the synapse→RELATE migration
# When you're satisfied, reclaim the backup table:
smem doctor --synapse-migration purge-backup

The migration is crash-resumable — if it is interrupted, the next connect (or smem doctor --synapse-migration retry) picks up where it left off.

Added

  • Native RELATE synapse graph + resumable, lock-guarded migration (copying → converting → verifying; version stamped only after verification).
  • GQL-accelerated get_path shortest-path with an automatic BFS fallback — uses SurrealDB 3.2's internal ISO GQL when available, falls back to BFS otherwise (correctness never depends on GQL).
  • smem doctor SurrealDB version check (fails when the server is < 3.2.0) and smem doctor --synapse-migration {status|retry|purge-backup}.
  • Parametric embedding dimension — the HNSW vector index is now built to match the embedding provider's output dimension. New SURREAL_MEMORY_EMBEDDING_DIMENSION env / [embedding].dimension config (0 = auto-derive, the default). Fixes silently-broken semantic search when the index dimension disagreed with the model.
  • SurrealDB maturation storage — maturation stages now persist on the SurrealDB backend (previously a base no-op), so long-lived memories report their real semantic maturity instead of 0%.

Performance

  • Semantic discovery now ranks candidate pairs over each neuron's stored embedding instead of re-embedding on every run (vectorised top-K with a pure-python fallback) and raises the candidate caps — much cheaper and surfaces far more cross-domain links.
  • Edge-first graph selection on the dashboard graph endpoint picks the most-connected nodes and keeps an edge only when both endpoints survive, fixing the near-empty graph that node-capping by id produced.

Fixed

  • Soft forget is excluded from recall immediately — a soft-forgotten memory no longer resurfaces in recall until the next consolidation.
  • Config-cache refresh — the REST process picks up new sync/embedding config after set_config(...) without a restart.
  • Rename-safe persistence — cognitive/compression/review-schedule upserts and consolidate target the current brain id after a rename instead of silently no-op'ing against a stale id.

Known behaviour

  • During the converting phase of the migration on a very large brain, synapse reads return empty until conversion completes (paged in batches of 500). The window is brief for typical brains and the migration is crash-resumable.
  • After the upgrade, external writers that insert flat rows (source_id/target_id) directly into the synapse table will fail — synapse is now a native RELATION and requires in/out edge endpoints (such writes were already violating the schema).

Compatibility & requirements

  • SurrealDB: ≥ 3.2.0 (the compose file now runs surrealdb/surrealdb:v3.2.0 with --allow-experimental gql --allow-eval-query).
  • Python: 3.11+.

Packages in this release

Artifact Name Registry
Python package surreal-memory 2.6.0 PyPI
Claude/OpenClaw plugin surrealmemory 2.6.0 npm
TypeScript SDK @acidkill/surreal-memory-client 2.6.0 npm

The VS Code extension and ClawHub plugin are planned for a future release.

Full changelog: https://github.com/acidkill/surreal-memory/blob/main/CHANGELOG.md#260--2026-07-07

Assets 4
Loading