v3.12.2 — safer consolidation, quieter memory

v3.12.2 — safer consolidation, quieter memory

This maintenance release brings together the changes since v3.12.1: safer
consolidation recovery and compression, bounded database operations, reliable
connection failure handling, and prevention of passive memory feedback from
memory reads. It also includes semantic snapshot retention and a dashboard
command-palette fix.

Highlights

• Protect important content during maintenance. Compression preserves
  original backups across tier advancement, protects pinned/shared neurons, and
  validates content lineage and completion receipts before replaying work.
• Make saved work resumable. Census pages account for SurrealDB's stored
  representation; summarize checkpoints handle omitted optional fields and
  resume their durable phases. Invalid state still stops safely.
• Reduce database overhead. Pruning uses native record targets, neuron reads
  use batches of 100, and semantic hashing has an optional verified OpenSSL path.
• Stop read/capture feedback. Recall, context, recap and explain no longer
  feed search text or returned memories into passive automatic capture.
  Successful calls to these tools are also excluded from tool-memory analytics.

Consolidation and data integrity

• Fingerprint and compare census pages in their stored form, accounting for
  omitted null keys and fiber metadata. Accept an idempotent second write of a
  dedup census completion marker. #283
• Read/delete selected synapses by native record ID in bounded, brain-scoped
  batches. #290
• Protect pinned neurons shared with unpinned fibers, including pending replay.
  #291
• Preserve native entity-reference IDs during promotion/deletion.
  #292
• Collapse only still-eligible superseded change-log updates in the current
  brain and report actual deletions. #293
• Resume summarization census phases and stop subsequent strategies after a
  progress-coordination failure. #294
• Clear the previous attempt's error on resume while preserving committed work
  and reference time. #297
• Accept an omitted optional summarize pending field and correctly clear and
  validate completed compression replay intents. Malformed present state still
  fails validation. #299
• Preserve compression originals across tiers, retain canonical lifecycle state
  during concurrent neuron updates, validate legacy compression lineage, and
  support numeric neuron record IDs. Unverifiable lineage stops recovery rather
  than overwriting later content. #300

Database reliability and performance

• Page the database changefeed before selecting a table, so unrelated writes do
  not hide semantic source barriers or relevant changes.
  #286
• Fail the active query when its WebSocket receiver stops, without automatically
  replaying a request that might already have executed. Later independent
  operations can reconnect; failed connection close is bounded to two seconds.
  #295
• Accept a concurrent schema-stamp conflict only after a fresh read confirms the
  exact expected version. #296
• Optionally accelerate resumable SHA-256 with output-verified OpenSSL, retaining
  the portable fallback and adding no mandatory dependency.
  #298
• Fetch neurons by native record ID in chunks of 100, preserving brain scoping
  and missing-record behavior. #301

Quieter memory and bounded retention

• Remove passive query/result capture from smem_recall, smem_context,
  smem_recap and smem_explain. Explicit smem_remember and
  smem_auto(action="process") remain available. Recall still writes normal
  activation, reinforcement, retrieval traces and configured reconsolidation;
  reconsolidate=false is not a fully read-only mode.
• Honor [tool_memory] enabled and blacklist prefixes in MCP analytics. Skip
  successful calls to the four read tools while retaining permitted failure
  diagnostics. Normalize native and namespaced MCP hook tool names and match
  blacklist prefixes against both forms. This prevents new feedback; it does
  not purge historical memories or tool events.
  #302
• After semantic_link completes, remove expired discovery snapshots in batches
  of at most 500. [maintenance] semantic_discovery_state_retention_days defaults
  to 7; 0 disables cleanup. Current and queued/running/paused/failed runs are
  protected. Cleanup failure is reported without failing the semantic strategy.
  #289

Dashboard and documentation

• Filter command-palette pages and Pro hints by the typed query (Ctrl/Cmd+K).
  #284
• Update English/Spanish READMEs, the full changelog, roadmap, FAQ, MCP guide and
  integration documentation. Add a consolidation/upgrade guide covering saved
  work, exit codes, data protection, retention and read/capture behavior.
• Align Python, plugin, npm integration/client and VS Code extension version
  metadata at 3.12.2. This does not introduce a new extension/client API.

Upgrade and compatibility

1. Let active maintenance finish before replacing its package. Back up the
   full selected database, including checkpoint and staging tables, and test
   restoration in isolation. A memory-only export is not a resumable-run backup.

2. After publication, update using your existing installer and retain every
   installed extra, connection setting and credential-refresh wrapper. Restart
   MCP/server processes and check smem --version and smem consolidate --help.

3. For an unfinished run, use:

   smem consolidate --resume --brain default

   For a new run, after the saved run completes, use:

   smem consolidate --brain default

4. Run one consolidation process per brain. --resume retains the original
   strategy set/reference time and skips completed strategies; it cannot be
   combined with explicit --strategy or --dry-run. A compatible ordinary
   invocation can still resume automatically.

5. A successful run requires completed and CLI exit 0. A budget pause exits
   1 and may need another resume. Run IDs, report dates and counters remain tied
   to the saved run; an unchanged printed cursor alone does not establish a
   stall. Investigate new errors rather than blindly retrying.

Schema remains v12; checkpoint epoch remains 3.11.0:checkpoint-v1. Valid
older census representations remain supported, except metadata-null pages that
never validated. Newly staged census pages are generally not readable by
3.12.1: do not downgrade in the middle of newly staged work or edit checkpoint
hashes to force compatibility. Retain a tested full backup for rollback.

Strategy budgets remain in effect. This release does not promise a single-call
consolidation for every brain, restore content already lost before the update,
or prove the health/integrity of a particular production database. Prune, merge
and lifecycle/compression maintenance can change or remove eligible records;
verify important recall and content after maintenance.

See the consolidation and upgrade guide
and full changelog.

Release preparation validation

• Ruff lint and formatting passed; mypy passed for all 362 source files.
• Full non-stress suite: 7,926 passed, 199 skipped, 1 expected failure.
• Version consistency, generated CLI/MCP/config references and scattered
  documentation-reference checks passed with no stale references.
• Strict documentation build and isolated wheel/sdist builds passed.
• GitHub CI:
  all 9 checks passed, including Python 3.11/3.12, live SurrealDB integration,
  documentation freshness and package build.

These checks validate the release candidate. Live database recovery, stress
tests and registry publication are separate acceptance steps.

Included work and acknowledgments

The release inventory covers all commits after v3.12.1, including regression
coverage, documentation/reference updates and integration merges. The functional
changes span 17 merged PRs: #283, #284, #286 and #289–#302, linked above.

Thanks to @RobertSigmundsson for the census, dashboard filtering, changefeed and
semantic snapshot retention contributions.

Release preparation and documentation: #303.

Full comparison: v3.12.1...v3.12.2