Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix: heal cached brain links during missing-memory catch-up (#11007)

Adam Eivyadc230caf165
diff --git a/docs/STORAGE.md b/docs/STORAGE.md
index 0f46c149d0..b6336b9fd4 100644
--- a/docs/STORAGE.md
+++ b/docs/STORAGE.md
@@ -533,8 +533,10 @@ unchanged. PostgreSQL backups include the table.
Boot DDL and migration 421 install the additive table. The bridge idempotently
imports valid legacy `data/brain/memory-bridge-map.json` links on first use,
-without overriding DB links, and rebuilds corrupt caches from the table. No
-seed is shipped. The JSON map remains a compatibility cache with one flush per
+without overriding DB links, and rebuilds corrupt caches from the table. If a
+legacy cache is already corrupt before any links have been imported and brain
+memories exist, sync refuses to guess their identities: restore that cache from
+backup. No seed is shipped. The JSON map remains a compatibility cache with one flush per
bulk sync; it is no longer the production identity authority.
## Adding a new data store? Answer these
diff --git a/server/services/brainMemoryBridge.js b/server/services/brainMemoryBridge.js
index 9e4dd80f68..8144ca5dd7 100644
--- a/server/services/brainMemoryBridge.js
+++ b/server/services/brainMemoryBridge.js
@@ -92,7 +92,7 @@ export async function loadBridgeMap({ readOnly = false } = {}) {
}
// Backfill old installs before trusting the cache. DB links win over stale
// file snapshots; missing rows are excluded so bulk catch-up can heal them.
- const map = await memory.getBrainMemoryLinks(legacyMap, { readOnly });
+ const map = await memory.getBrainMemoryLinks(legacyMap, { readOnly, ...(rebuild ? { recover: true } : {}) });
if (!readOnly) {
bridgeMap = map;
if (rebuild) await saveBridgeMap();
@@ -315,7 +315,10 @@ const makeEmbeddedChecker = (map, missingMemIds) => (key) => {
};
export async function syncAllBrainData({ dryRun = false, refresh = false, onlyMissing = false } = {}) {
- const map = await loadBridgeMap({ readOnly: dryRun });
+ // Revalidate cached ids once per bulk walk: a memory can be purged after
+ // this process loaded the cache. A stale key must not count as embedded.
+ const map = await memory.getBrainMemoryLinks(
+ await loadBridgeMap({ readOnly: dryRun }), { readOnly: dryRun });
const stats = { synced: 0, skipped: 0, errors: 0, archived: 0 };
let bridgeMapChanged = false;
const deferredMapSave = {
@@ -480,7 +483,8 @@ export async function syncAllBrainData({ dryRun = false, refresh = false, onlyMi
* `listLiveIds` reads only the ids it has never resolved.
*/
export async function getEmbeddingCoverage() {
- const map = await loadBridgeMap({ readOnly: true });
+ const map = await memory.getBrainMemoryLinks(
+ await loadBridgeMap({ readOnly: true }), { readOnly: true });
const missingMemIds = await memory.getMemoryIdsMissingEmbedding().catch(() => new Set());
const isEmbedded = makeEmbeddedChecker(map, missingMemIds);
diff --git a/server/services/brainMemoryBridge.test.js b/server/services/brainMemoryBridge.test.js
index feacdf057c..4d5451726e 100644
--- a/server/services/brainMemoryBridge.test.js
+++ b/server/services/brainMemoryBridge.test.js
@@ -812,6 +812,22 @@ describe('brain bridge durable identity (#11007)', () => {
{ 'people:example': 'legacy-1' }, { readOnly: false });
});
+ it('Embed missing heals a purged row even when the process already cached its old id', async () => {
+ const backend = await import('./memoryBackend.js');
+ bridgeFileContents = JSON.stringify({ 'people:example': 'purged-1' });
+ const bridge = await loadBridge();
+ await bridge.loadBridgeMap();
+ getAll.mockImplementation(async type => type === 'people'
+ ? [{ id: 'example', name: 'Example' }] : []);
+ backend.getBrainMemoryLinks.mockResolvedValueOnce({});
+ updateMemory.mockResolvedValueOnce(null);
+ const stats = await bridge.syncAllBrainData({ onlyMissing: true });
+ expect(stats.synced).toBe(1);
+ expect(createMemory).toHaveBeenCalledTimes(1);
+ expect(JSON.parse(bridgeFileContents)['people:example']).not.toBe('purged-1');
+ expect(atomicWrite).toHaveBeenCalledTimes(1);
+ });
+
it('drains overlapping JSONL adds through the in-flight resync and preserves every cache key', async () => {
const backend = await import('./memoryBackend.js');
const { brainEvents } = await import('./brainStorage.js');
diff --git a/server/services/memoryBackend.js b/server/services/memoryBackend.js
index e568b9cc90..f000baf4a9 100644
--- a/server/services/memoryBackend.js
+++ b/server/services/memoryBackend.js
@@ -114,7 +114,9 @@ export async function createMemory(data, embedding) {
// delegates these operations to the transactional PostgreSQL implementation.
export async function getBrainMemoryLinks(legacyMap = {}, options) {
const b = await getBackend();
- return b.getBrainMemoryLinks ? b.getBrainMemoryLinks(legacyMap, options) : legacyMap;
+ if (b.getBrainMemoryLinks) return b.getBrainMemoryLinks(legacyMap, options);
+ if (options?.recover) throw new Error('File-mode brain bridge cache is corrupt; restore it from backup');
+ return legacyMap;
}
export async function upsertBrainMemory(key, data, embedding, legacyId) {
diff --git a/server/services/memoryDB.db.test.js b/server/services/memoryDB.db.test.js
index 76667444a2..33ac102af9 100644
--- a/server/services/memoryDB.db.test.js
+++ b/server/services/memoryDB.db.test.js
@@ -1204,6 +1204,8 @@ describe.skipIf(!runDb)('durable brain memory identity (#11007)', () => {
it('reuses a legacy row, ignores a stale cache, and heals a purged target', async () => {
const legacy = await memoryDB.createMemory(data, VEC_A);
+ await expect(memoryDB.getBrainMemoryLinks({}, { recover: true }))
+ .rejects.toThrow('no durable links exist yet');
expect(await memoryDB.getBrainMemoryLinks({ 'projects:example': legacy.id }, { readOnly: true })).toEqual({
'projects:example': legacy.id,
});
diff --git a/server/services/memoryDB.js b/server/services/memoryDB.js
index e8e5430159..4414cd6994 100644
--- a/server/services/memoryDB.js
+++ b/server/services/memoryDB.js
@@ -157,8 +157,16 @@ export async function createMemory(data, embedding = null) {
* only live links. A purged row must not make bulk sync skip its brain record.
* The table is machine-local; memory ids differ across installs.
*/
-export async function getBrainMemoryLinks(legacyMap = {}, { readOnly = false } = {}) {
+export async function getBrainMemoryLinks(legacyMap = {}, { readOnly = false, recover = false } = {}) {
return withTransaction(async client => {
+ if (recover) {
+ const unmigrated = await client.query(`
+ SELECT 1 WHERE EXISTS (SELECT 1 FROM memories WHERE source_app_id = 'brain')
+ AND NOT EXISTS (SELECT 1 FROM brain_memory_links)`);
+ if (unmigrated.rows.length) {
+ throw new Error('Brain bridge cache is corrupt and no durable links exist yet; restore the legacy map from backup before syncing');
+ }
+ }
if (!readOnly && Object.keys(legacyMap).length) {
await client.query(`
INSERT INTO brain_memory_links (bridge_key, memory_id)