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: preserve brain memory links across interrupted syncs (#11007)

Adam Eivy8b7c3c3f58c0
diff --git a/docs/STORAGE.md b/docs/STORAGE.md
index 47dc1f8b10..0f46c149d0 100644
--- a/docs/STORAGE.md
+++ b/docs/STORAGE.md
@@ -522,6 +522,21 @@ Received counters never replace local counters: a peer replacement snapshots thi
machine's prior text and advances its own revision. Rejection now archives with a
reason; explicit purge deletes the memory and its history.
+### Brain-to-memory identity
+
+`brain_memory_links` is machine-local `db-primary` identity keyed by brain
+`type:id`. Its memory UUID is committed in the same transaction as the memory
+write. The link intentionally survives a memory purge so the next sync can heal
+it; live-map reads exclude missing targets. It does not federate: each machine
+builds its own bridge using its own memory ids. Existing memory federation stays
+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
+bulk sync; it is no longer the production identity authority.
+
## Adding a new data store? Answer these
Apply this checklist to **every new feature that persists data**, and require it in PR review. A new `data/*.json` store must *justify* itself against these questions — the default for app-native records is PostgreSQL.
diff --git a/scripts/migrations/421-brain-memory-links.js b/scripts/migrations/421-brain-memory-links.js
new file mode 100644
index 0000000000..d25f15ffb0
--- /dev/null
+++ b/scripts/migrations/421-brain-memory-links.js
@@ -0,0 +1,11 @@
+/**
+ * Brain bridge identity is db-primary. Boot DDL installs the additive table;
+ * first bridge use imports valid legacy map links before any memory writes.
+ * No seed: links derive from each install's existing map and memory rows.
+ */
+export default {
+ async up() {
+ console.log('🧠 Brain memory links are installed by ensureSchema and backfilled on first bridge use');
+ return { success: true };
+ }
+};
diff --git a/server/lib/db/schema/core.js b/server/lib/db/schema/core.js
index bef42bbb0d..0d0e4b8137 100644
--- a/server/lib/db/schema/core.js
+++ b/server/lib/db/schema/core.js
@@ -79,6 +79,11 @@ END$$`,
];
export const coreDdl = [
+ // Deliberately no FK: the bridge repairs a purged target on its next sync.
+ `CREATE TABLE IF NOT EXISTS brain_memory_links (
+ bridge_key TEXT PRIMARY KEY,
+ memory_id UUID NOT NULL
+ )`,
`CREATE TABLE IF NOT EXISTS deep_audit_ledgers (
id TEXT PRIMARY KEY,
app_id TEXT NOT NULL,
diff --git a/server/scripts/init-db.sql b/server/scripts/init-db.sql
index efe63d8ea3..cacfd8b346 100644
--- a/server/scripts/init-db.sql
+++ b/server/scripts/init-db.sql
@@ -2441,3 +2441,9 @@ CREATE TABLE IF NOT EXISTS deep_audit_ledgers (
ledger JSONB NOT NULL,
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
+
+-- Machine-local brain bridge identity, retained across a memory purge for healing.
+CREATE TABLE IF NOT EXISTS brain_memory_links (
+ bridge_key TEXT PRIMARY KEY,
+ memory_id UUID NOT NULL
+);
diff --git a/server/services/brainMemoryBridge.js b/server/services/brainMemoryBridge.js
index 441992bf68..9e4dd80f68 100644
--- a/server/services/brainMemoryBridge.js
+++ b/server/services/brainMemoryBridge.js
@@ -63,27 +63,62 @@ const RECONCILABLE_TYPES = [...BRIDGED_ENTITY_TYPES, 'journals'];
// Maps "brainType:brainId" → memoryId so updates hit the same memory entry
let bridgeMap = null;
+let bridgeMapLoading = null;
+let mapWriteTail = Promise.resolve();
-export async function loadBridgeMap() {
+export async function loadBridgeMap({ readOnly = false } = {}) {
if (bridgeMap) return bridgeMap;
- if (!existsSync(BRIDGE_MAP_PATH)) {
- bridgeMap = {};
- return bridgeMap;
- }
- const raw = await readFile(BRIDGE_MAP_PATH, 'utf-8');
+ if (bridgeMapLoading) return bridgeMapLoading;
+ const load = async () => {
+ let legacyMap = {};
+ let rebuild = false;
+ const raw = await readFile(BRIDGE_MAP_PATH, 'utf-8').catch(err => {
+ if (err.code === 'ENOENT') return null;
+ throw err;
+ });
+ if (raw !== null) {
+ try {
+ legacyMap = JSON.parse(raw);
+ if (!legacyMap || Array.isArray(legacyMap) || typeof legacyMap !== 'object') {
+ throw new Error('Invalid bridge map shape');
+ }
+ legacyMap = Object.fromEntries(Object.entries(legacyMap)
+ .filter(([, id]) => typeof id === 'string' && id));
+ } catch {
+ console.warn('⚠️ Corrupt brain bridge cache; rebuilding from durable memory links');
+ legacyMap = {};
+ rebuild = true;
+ }
+ }
+ // 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 });
+ if (!readOnly) {
+ bridgeMap = map;
+ if (rebuild) await saveBridgeMap();
+ }
+ return map;
+ };
+ // Read-only previews neither migrate links nor cache an unmigrated map.
+ if (readOnly) return load();
+ bridgeMapLoading = load();
try {
- bridgeMap = JSON.parse(raw);
- } catch (err) {
- console.error(`❌ Corrupt bridge map, resetting: ${err.message}`);
- bridgeMap = {};
+ return await bridgeMapLoading;
+ } finally {
+ bridgeMapLoading = null;
}
- return bridgeMap;
}
-async function saveBridgeMap() {
- const dir = dirname(BRIDGE_MAP_PATH);
- if (!existsSync(dir)) await ensureDir(dir);
- await atomicWrite(BRIDGE_MAP_PATH, bridgeMap);
+function saveBridgeMap() {
+ // Snapshot only after the preceding rename completes. All writers, including
+ // bulk catch-up and delete handlers, share this tail.
+ const write = mapWriteTail.then(async () => {
+ const dir = dirname(BRIDGE_MAP_PATH);
+ if (!existsSync(dir)) await ensureDir(dir);
+ await atomicWrite(BRIDGE_MAP_PATH, bridgeMap);
+ });
+ mapWriteTail = write.catch(() => {});
+ return write;
}
export function bridgeKey(brainType, brainId) {
@@ -244,27 +279,14 @@ export async function syncBrainRecord(brainType, record, { deferMapSave = false,
.generateMemoryEmbedding(memoryData, { source: record.source, sourceRef: record.sourceRef })
.catch(() => null);
- if (existingMemoryId) {
- // Update existing memory. Force status:'active' so a record that was
- // archived for a synced-in delete/archive and later came back live
- // (un-deleted on a peer, or un-archived) is searchable again — memory
- // search filters out archived rows, so without this the resurrected
- // record would stay invisible (issue #1080 review finding).
- const updated = await memory.updateMemory(existingMemoryId, { ...memoryData, status: 'active' });
- if (updated && embedding) {
- await memory.updateMemoryEmbedding(existingMemoryId, embedding);
- }
- console.log(`🧠🔗 Updated brain→memory: ${brainType}/${record.id} → ${existingMemoryId}`);
- return existingMemoryId;
+ const saved = await memory.upsertBrainMemory(key, memoryData, embedding, existingMemoryId);
+ if (map[key] !== saved.id) {
+ map[key] = saved.id;
+ onMapChanged?.();
+ if (!deferMapSave) await saveBridgeMap();
}
-
- // Create new memory
- const created = await memory.createMemory(memoryData, embedding);
- map[key] = created.id;
- onMapChanged?.();
- if (!deferMapSave) await saveBridgeMap();
- console.log(`🧠🔗 Created brain→memory: ${brainType}/${record.id} → ${created.id}`);
- return created.id;
+ console.log(`🧠🔗 Synced brain→memory: ${brainType}/${record.id} → ${saved.id}`);
+ return saved.id;
}
/**
@@ -293,7 +315,7 @@ const makeEmbeddedChecker = (map, missingMemIds) => (key) => {
};
export async function syncAllBrainData({ dryRun = false, refresh = false, onlyMissing = false } = {}) {
- const map = await loadBridgeMap();
+ const map = await loadBridgeMap({ readOnly: dryRun });
const stats = { synced: 0, skipped: 0, errors: 0, archived: 0 };
let bridgeMapChanged = false;
const deferredMapSave = {
@@ -458,7 +480,7 @@ 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();
+ const map = await loadBridgeMap({ readOnly: true });
const missingMemIds = await memory.getMemoryIdsMissingEmbedding().catch(() => new Set());
const isEmbedded = makeEmbeddedChecker(map, missingMemIds);
@@ -574,7 +596,9 @@ export async function resyncBrainRecord(brainType, id, { hardDelete = false } =
// delete naturally lands in the archive/hard-delete branch.
const record = brainType === 'journals'
? await getJournal(id)
- : await brainStorage.getById(brainType, id);
+ : JSONL_TYPES.includes(brainType)
+ ? (await readJsonlStore(brainType)).find(record => record.id === id)
+ : await brainStorage.getById(brainType, id);
if (!record) {
// Truly gone (tombstoned). A genuine local user delete hard-prunes the row;
// a sync-driven delete stays soft so a peer un-delete can resurrect it.
@@ -661,9 +685,7 @@ export function queueResync(records) {
function handleJsonlAdded(brainType, record) {
if (!record?.id) return;
- syncBrainRecord(brainType, record).catch(err => {
- console.error(`❌ Brain bridge sync failed for ${brainType}/${record.id}: ${err.message}`);
- });
+ queueResync([{ type: brainType, id: record.id }]);
}
// ─── Init ───────────────────────────────────────────────────────────────────
diff --git a/server/services/brainMemoryBridge.test.js b/server/services/brainMemoryBridge.test.js
index 86d3a01773..feacdf057c 100644
--- a/server/services/brainMemoryBridge.test.js
+++ b/server/services/brainMemoryBridge.test.js
@@ -41,6 +41,13 @@ vi.mock('../lib/fileUtils.js', () => ({
}));
vi.mock('./memoryBackend.js', () => ({
createMemory, updateMemory, updateMemoryEmbedding, purgeMemory, getMemoryIdsMissingEmbedding,
+ getBrainMemoryLinks: vi.fn(async legacyMap => legacyMap),
+ upsertBrainMemory: vi.fn(async (_key, data, embedding, legacyId) => {
+ const updated = legacyId && await updateMemory(legacyId, { ...data, status: 'active' });
+ if (!updated) return createMemory(data, embedding);
+ if (embedding) await updateMemoryEmbedding(legacyId, embedding);
+ return { ...updated, id: legacyId };
+ }),
}));
vi.mock('./memoryEmbeddings.js', () => ({ generateMemoryEmbedding }));
vi.mock('./brainStorage.js', () => {
@@ -755,3 +762,94 @@ describe('brainMemoryBridge — SongBook enrollment (issue #4105)', () => {
expect(refreshed.archived).toBe(1);
});
});
+
+describe('brain bridge durable identity (#11007)', () => {
+ it('recovers after the memory commit succeeds but the cache save fails', async () => {
+ const backend = await import('./memoryBackend.js');
+ const durable = {};
+ let inserted = 0;
+ await backend.upsertBrainMemory.withImplementation(async key => {
+ durable[key] ??= `durable-${++inserted}`;
+ return { id: durable[key] };
+ }, async () => {
+ await backend.getBrainMemoryLinks.withImplementation(async () => ({ ...durable }), async () => {
+ const first = await loadBridge();
+ atomicWrite.mockRejectedValueOnce(new Error('simulated lost cache save'));
+ await expect(first.syncBrainRecord('people', { id: 'example', name: 'Example' }))
+ .rejects.toThrow('simulated lost cache save');
+ // Reset only process state; the durable backend survived the crash.
+ const restarted = await loadBridge();
+ expect(await restarted.syncBrainRecord('people', { id: 'example', name: 'Updated example' }))
+ .toBe('durable-1');
+ expect(inserted).toBe(1);
+ expect(await restarted.loadBridgeMap()).toEqual({ 'people:example': 'durable-1' });
+ });
+ });
+ });
+
+ it('rebuilds a corrupt cache from durable links before updating the record', async () => {
+ const backend = await import('./memoryBackend.js');
+ bridgeFileContents = '{broken';
+ await backend.getBrainMemoryLinks.withImplementation(async () => ({ 'people:example': 'durable-1' }), async () => {
+ const bridge = await loadBridge();
+ await bridge.syncBrainRecord('people', { id: 'example', name: 'Example' });
+ expect(createMemory).not.toHaveBeenCalled();
+ expect(updateMemory).toHaveBeenCalledWith('durable-1', expect.objectContaining({ status: 'active' }));
+ expect(JSON.parse(bridgeFileContents)).toEqual({ 'people:example': 'durable-1' });
+ });
+ });
+
+ it('keeps a cold dry run write-free and still imports links on the subsequent write', async () => {
+ const backend = await import('./memoryBackend.js');
+ bridgeFileContents = JSON.stringify({ 'people:example': 'legacy-1' });
+ const bridge = await loadBridge();
+ await bridge.syncAllBrainData({ dryRun: true });
+ expect(backend.getBrainMemoryLinks).toHaveBeenLastCalledWith(
+ { 'people:example': 'legacy-1' }, { readOnly: true });
+ expect(atomicWrite).not.toHaveBeenCalled();
+ await bridge.syncBrainRecord('people', { id: 'example', name: 'Example' });
+ expect(backend.getBrainMemoryLinks).toHaveBeenLastCalledWith(
+ { 'people:example': 'legacy-1' }, { readOnly: false });
+ });
+
+ 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');
+ const bridge = await loadBridge();
+ bridge.initBridge();
+ getById.mockResolvedValue({ id: 'example', name: 'Example' });
+ getDigests.mockResolvedValue([
+ { id: 'digest-one', digestText: 'First example digest' },
+ { id: 'digest-two', digestText: 'Second example digest' },
+ ]);
+ let releaseWrite;
+ let enteredWrite;
+ const entered = new Promise(resolve => { enteredWrite = resolve; });
+ const held = new Promise(resolve => { releaseWrite = resolve; });
+ atomicWrite.mockImplementationOnce(async (_path, data) => {
+ const snapshot = JSON.stringify(data);
+ enteredWrite();
+ await held;
+ bridgeFileContents = snapshot;
+ });
+ await createMemory.withImplementation(async data => ({ id: `memory-${data.content}` }), async () => {
+ bridge.queueResync([{ type: 'people', id: 'example' }]);
+ const flush = bridge.flushPendingResync();
+ await entered;
+ try {
+ brainEvents.emit('digests:added', { id: 'digest-one' });
+ brainEvents.emit('digests:added', { id: 'digest-two' });
+ brainEvents.emit('digests:added', { id: 'digest-one' });
+ await bridge.flushPendingResync();
+ expect(backend.upsertBrainMemory).toHaveBeenCalledTimes(1);
+ } finally {
+ releaseWrite();
+ await flush;
+ }
+ expect(backend.upsertBrainMemory).toHaveBeenCalledTimes(3);
+ expect(Object.keys(JSON.parse(bridgeFileContents)).sort()).toEqual([
+ 'digests:digest-one', 'digests:digest-two', 'people:example',
+ ]);
+ });
+ });
+});
diff --git a/server/services/memoryBackend.js b/server/services/memoryBackend.js
index 8102c85c30..e568b9cc90 100644
--- a/server/services/memoryBackend.js
+++ b/server/services/memoryBackend.js
@@ -110,6 +110,22 @@ export async function createMemory(data, embedding) {
return b.createMemory(data, embedding);
}
+// File mode is a development/test-only compatibility path. Production always
+// 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;
+}
+
+export async function upsertBrainMemory(key, data, embedding, legacyId) {
+ const b = await getBackend();
+ if (b.upsertBrainMemory) return b.upsertBrainMemory(key, data, embedding, legacyId);
+ const updated = legacyId && await b.updateMemory(legacyId, { ...data, status: 'active' });
+ if (!updated) return b.createMemory(data, embedding);
+ if (embedding) await b.updateMemoryEmbedding(legacyId, embedding);
+ return updated;
+}
+
export async function peekMemory(id) {
const b = await getBackend();
return b.peekMemory(id);
diff --git a/server/services/memoryDB.db.test.js b/server/services/memoryDB.db.test.js
index 5e203a4f9f..76667444a2 100644
--- a/server/services/memoryDB.db.test.js
+++ b/server/services/memoryDB.db.test.js
@@ -1178,3 +1178,57 @@ describe.skipIf(!runDb)('memory history and stale-write contract (#10494)', () =
expect(await memoryDB.getMemoryVersions(original.id)).toEqual([]);
});
});
+
+
+describe.skipIf(!runDb)('durable brain memory identity (#11007)', () => {
+ beforeEach(async () => {
+ await query('DELETE FROM brain_memory_links');
+ await resetMemories();
+ });
+
+ const data = { type: 'fact', content: 'Example brain project', sourceAppId: 'brain', category: 'project' };
+
+ it('retries after a lost map save and serializes overlapping first writes', async () => {
+ // There is deliberately no file save between these independent calls.
+ const results = await Promise.all([
+ memoryDB.upsertBrainMemory('projects:example', data, VEC_A),
+ memoryDB.upsertBrainMemory('projects:example', data, VEC_A),
+ ]);
+ expect(results[0].id).toBe(results[1].id);
+ const retry = await memoryDB.upsertBrainMemory('projects:example', { ...data, content: 'Updated example' });
+ expect(retry.id).toBe(results[0].id);
+ expect((await memoryDB.getMemories({ appId: 'brain' })).total).toBe(1);
+ expect(await memoryDB.getBrainMemoryLinks()).toEqual({ 'projects:example': retry.id });
+ expect((await memoryDB.getMemoryVersions(retry.id)).length).toBe(1);
+ });
+
+ it('reuses a legacy row, ignores a stale cache, and heals a purged target', async () => {
+ const legacy = await memoryDB.createMemory(data, VEC_A);
+ expect(await memoryDB.getBrainMemoryLinks({ 'projects:example': legacy.id }, { readOnly: true })).toEqual({
+ 'projects:example': legacy.id,
+ });
+ expect((await query('SELECT * FROM brain_memory_links')).rows).toEqual([]);
+ expect(await memoryDB.getBrainMemoryLinks({ 'projects:example': legacy.id })).toEqual({
+ 'projects:example': legacy.id,
+ });
+ const saved = await memoryDB.upsertBrainMemory('projects:example', data);
+ expect(saved.id).toBe(legacy.id);
+ await memoryDB.purgeMemory(saved.id);
+ expect(await memoryDB.getBrainMemoryLinks({ 'projects:example': saved.id })).toEqual({});
+ const healed = await memoryDB.upsertBrainMemory('projects:example', data, VEC_A, saved.id);
+ expect(healed.id).not.toBe(saved.id);
+ expect(await memoryDB.getBrainMemoryLinks({ 'projects:example': saved.id })).toEqual({
+ 'projects:example': healed.id,
+ });
+ expect((await memoryDB.getMemories({ appId: 'brain' })).total).toBe(1);
+ });
+
+ it('rolls back the reserved link when the memory insert fails', async () => {
+ await expect(memoryDB.upsertBrainMemory('projects:example', { ...data, type: 'invalid-type-exceeding-column-length' }))
+ .rejects.toThrow();
+ expect((await query('SELECT * FROM brain_memory_links')).rows).toEqual([]);
+ expect((await memoryDB.getMemories({ appId: 'brain' })).total).toBe(0);
+ });
+
+ afterAll(async () => { await query('DELETE FROM brain_memory_links'); });
+});
diff --git a/server/services/memoryDB.js b/server/services/memoryDB.js
index 1fe6396536..e8e5430159 100644
--- a/server/services/memoryDB.js
+++ b/server/services/memoryDB.js
@@ -92,7 +92,7 @@ function embeddingColumns(embedding) {
/**
* Create a new memory
*/
-export async function createMemory(data, embedding = null) {
+async function insertMemory(client, data, embedding) {
const id = uuidv4();
const summary = data.summary || generateSummary(data.content);
const now = new Date().toISOString();
@@ -100,55 +100,118 @@ export async function createMemory(data, embedding = null) {
const originInstanceId = await getInstanceId();
const embeddingCol = embeddingColumns(embedding);
- const memory = await withTransaction(async (client) => {
- const result = await client.query(
- `INSERT INTO memories (
- id, type, content, summary, category, tags,
- embedding, embedding_model, confidence, importance,
- source_task_id, source_agent_id, source_app_id,
- expires_at, status, created_at, updated_at, origin_instance_id
- ) VALUES (
- $1, $2, $3, $4, $5, $6,
- $7, $8, $9, $10,
- $11, $12, $13,
- $14, $15, $16, $17, $18
- ) RETURNING *`,
- [
- id, data.type, data.content, summary, data.category || 'other', data.tags || [],
- embeddingCol.value,
- embeddingCol.model,
- data.confidence ?? 0.8, data.importance ?? 0.5,
- data.sourceTaskId || null, data.sourceAgentId || null, data.sourceAppId || null,
- data.expiresAt || null, data.status || 'active', now, now, originInstanceId
- ]
- );
+ const result = await client.query(
+ `INSERT INTO memories (
+ id, type, content, summary, category, tags,
+ embedding, embedding_model, confidence, importance,
+ source_task_id, source_agent_id, source_app_id,
+ expires_at, status, created_at, updated_at, origin_instance_id
+ ) VALUES (
+ $1, $2, $3, $4, $5, $6,
+ $7, $8, $9, $10,
+ $11, $12, $13,
+ $14, $15, $16, $17, $18
+ ) RETURNING *`,
+ [
+ id, data.type, data.content, summary, data.category || 'other', data.tags || [],
+ embeddingCol.value,
+ embeddingCol.model,
+ data.confidence ?? 0.8, data.importance ?? 0.5,
+ data.sourceTaskId || null, data.sourceAgentId || null, data.sourceAppId || null,
+ data.expiresAt || null, data.status || 'active', now, now, originInstanceId
+ ]
+ );
- const mem = rowToMemory(result.rows[0]);
- // Attach the original embedding array (pgvector may return string
- // representation) — but ONLY when it was actually stored. A
- // wrong-dimension embedding is dropped to NULL by embeddingColumns(), and
- // echoing the rejected array back would tell the caller the record is
- // embedded when it isn't (embedding_model is already NULL), hiding it from
- // re-embed logic that gates on the returned value. Mirrors
- // updateMemoryEmbedding().
- mem.embedding = embeddingCol.value ? embedding : null;
- // Store related memories as links
- if (data.relatedMemories?.length > 0) {
- for (const relId of data.relatedMemories) {
- await client.query(
- 'INSERT INTO memory_links (source_id, target_id) VALUES ($1, $2) ON CONFLICT DO NOTHING',
- [id, relId]
- );
- }
- mem.relatedMemories = data.relatedMemories;
+ const mem = rowToMemory(result.rows[0]);
+ // Attach the original embedding array (pgvector may return string
+ // representation) — but ONLY when it was actually stored. A
+ // wrong-dimension embedding is dropped to NULL by embeddingColumns(), and
+ // echoing the rejected array back would tell the caller the record is
+ // embedded when it isn't (embedding_model is already NULL), hiding it from
+ // re-embed logic that gates on the returned value. Mirrors
+ // updateMemoryEmbedding().
+ mem.embedding = embeddingCol.value ? embedding : null;
+ // Store related memories as links
+ if (data.relatedMemories?.length > 0) {
+ for (const relId of data.relatedMemories) {
+ await client.query(
+ 'INSERT INTO memory_links (source_id, target_id) VALUES ($1, $2) ON CONFLICT DO NOTHING',
+ [id, relId]
+ );
}
+ mem.relatedMemories = data.relatedMemories;
+ }
- return mem;
- });
+ return mem;
+}
+export async function createMemory(data, embedding = null) {
+ const memory = await withTransaction(client => insertMemory(client, data, embedding));
console.log(`🧠 Memory created: ${memory.type} - ${memory.summary.substring(0, 50)}...`);
- cosEvents.emit('memory:created', { id, type: memory.type, summary: memory.summary });
+ cosEvents.emit('memory:created', { id: memory.id, type: memory.type, summary: memory.summary });
+ return memory;
+}
+/**
+ * Import legacy links without replacing an authoritative DB link, then return
+ * 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 } = {}) {
+ return withTransaction(async client => {
+ if (!readOnly && Object.keys(legacyMap).length) {
+ await client.query(`
+ INSERT INTO brain_memory_links (bridge_key, memory_id)
+ SELECT legacy.key, m.id FROM jsonb_each_text($1::jsonb) legacy
+ JOIN memories m ON m.id::text = legacy.value AND m.source_app_id = 'brain'
+ ORDER BY legacy.key
+ ON CONFLICT (bridge_key) DO NOTHING`, [JSON.stringify(legacyMap)]);
+ }
+ const result = await client.query(`
+ SELECT l.bridge_key, l.memory_id FROM brain_memory_links l
+ JOIN memories m ON m.id = l.memory_id
+ UNION ALL
+ SELECT legacy.key, m.id FROM jsonb_each_text($1::jsonb) legacy
+ JOIN memories m ON m.id::text = legacy.value AND m.source_app_id = 'brain'
+ WHERE NOT EXISTS (SELECT 1 FROM brain_memory_links l WHERE l.bridge_key = legacy.key)`,
+ [JSON.stringify(legacyMap)]);
+ return Object.fromEntries(result.rows.map(row => [row.bridge_key, row.memory_id]));
+ });
+}
+
+/**
+ * The link row is also the per-key transaction lock, including the first insert.
+ * No FK: retaining a dangling link lets the next upsert heal a purged memory.
+ * All memory/history/feed writes and the link replacement commit together.
+ */
+export async function upsertBrainMemory(key, data, embedding = null, legacyId = null) {
+ const result = await withTransaction(async client => {
+ await client.query(
+ 'INSERT INTO brain_memory_links (bridge_key, memory_id) VALUES ($1, $2) ON CONFLICT DO NOTHING',
+ [key, UUID_RE.test(legacyId ?? '') ? legacyId : uuidv4()]
+ );
+ const link = await client.query(
+ 'SELECT memory_id FROM brain_memory_links WHERE bridge_key = $1 FOR UPDATE', [key]
+ );
+ const id = link.rows[0].memory_id;
+ let memory = await updateMemoryWithClient(client, id, { ...data, status: 'active' });
+ const created = !memory;
+ if (created) {
+ memory = await insertMemory(client, data, embedding);
+ await client.query('UPDATE brain_memory_links SET memory_id = $2 WHERE bridge_key = $1', [key, memory.id]);
+ } else if (embedding) {
+ const columns = embeddingColumns(embedding);
+ await client.query('UPDATE memories SET embedding = $1, embedding_model = $2 WHERE id = $3',
+ [columns.value, columns.model, id]);
+ memory.embedding = columns.value ? embedding : null;
+ memory.embeddingModel = columns.model;
+ }
+ return { memory, created };
+ });
+ const { memory, created } = result;
+ cosEvents.emit(created ? 'memory:created' : 'memory:updated', created
+ ? { id: memory.id, type: memory.type, summary: memory.summary }
+ : { id: memory.id, updates: data });
return memory;
}
@@ -302,52 +365,54 @@ export async function getMemories(options = {}) {
/**
* Update a memory
*/
-export async function updateMemory(id, updates) {
- const memory = await withTransaction(async (client) => {
- const existing = await client.query('SELECT * FROM memories WHERE id = $1 FOR UPDATE', [id]);
- if (!existing.rows.length) return null;
- const row = existing.rows[0];
- if (updates.expectedVersion !== undefined && updates.expectedVersion !== row.version) {
- throw new ServerError('Memory changed since it was loaded. Reload before saving.', {
- status: 409, code: 'MEMORY_VERSION_CONFLICT'
- });
- }
- await client.query(
- "SELECT set_config('portos.memory_changed_by', $1, true), set_config('portos.memory_change_reason', $2, true)",
- [updates.changedBy ?? '', updates.changeReason ?? '']
- );
- const values = { ...updates };
- if (values.status === 'archived' && values.changeReason !== undefined) values.archiveReason = values.changeReason;
- if (typeof values.content === 'string' && values.summary === undefined) {
- values.summary = generateSummary(values.content);
- }
- const fieldMap = {
- content: 'content', summary: 'summary', type: 'type', category: 'category',
- tags: 'tags', confidence: 'confidence', importance: 'importance', status: 'status',
- expiresAt: 'expires_at', sourceAppId: 'source_app_id', archiveReason: 'archive_reason'
- };
- const params = [];
- const fields = Object.entries(fieldMap).filter(([key]) => values[key] !== undefined)
- .map(([key, column]) => { params.push(values[key]); return `${column} = $${params.length}`; });
- // The row trigger saves OLD and increments version in this same transaction,
- // including writes from sync. Operational-only writes do not create history.
- const updated = fields.length ? (await client.query(
- `UPDATE memories SET ${fields.join(', ')} WHERE id = $${params.length + 1} RETURNING *`,
- [...params, id]
- )).rows[0] : row;
- if (updates.relatedMemories) {
- // Legacy edits replace only the symmetric relation; preserve typed provenance.
- await client.query("DELETE FROM memory_links WHERE source_id = $1 AND link_type = 'related'", [id]);
- if (updates.relatedMemories.length) {
- const slots = updates.relatedMemories.map((_, i) => `($1, $${i + 2})`).join(', ');
- await client.query(`INSERT INTO memory_links (source_id, target_id) VALUES ${slots} ON CONFLICT DO NOTHING`,
- [id, ...updates.relatedMemories]);
- }
- await client.query('UPDATE memories SET updated_at = NOW() WHERE id = $1', [id]);
+async function updateMemoryWithClient(client, id, updates) {
+ const existing = await client.query('SELECT * FROM memories WHERE id = $1 FOR UPDATE', [id]);
+ if (!existing.rows.length) return null;
+ const row = existing.rows[0];
+ if (updates.expectedVersion !== undefined && updates.expectedVersion !== row.version) {
+ throw new ServerError('Memory changed since it was loaded. Reload before saving.', {
+ status: 409, code: 'MEMORY_VERSION_CONFLICT'
+ });
+ }
+ await client.query(
+ "SELECT set_config('portos.memory_changed_by', $1, true), set_config('portos.memory_change_reason', $2, true)",
+ [updates.changedBy ?? '', updates.changeReason ?? '']
+ );
+ const values = { ...updates };
+ if (values.status === 'archived' && values.changeReason !== undefined) values.archiveReason = values.changeReason;
+ if (typeof values.content === 'string' && values.summary === undefined) {
+ values.summary = generateSummary(values.content);
+ }
+ const fieldMap = {
+ content: 'content', summary: 'summary', type: 'type', category: 'category',
+ tags: 'tags', confidence: 'confidence', importance: 'importance', status: 'status',
+ expiresAt: 'expires_at', sourceAppId: 'source_app_id', archiveReason: 'archive_reason'
+ };
+ const params = [];
+ const fields = Object.entries(fieldMap).filter(([key]) => values[key] !== undefined)
+ .map(([key, column]) => { params.push(values[key]); return `${column} = $${params.length}`; });
+ // The row trigger saves OLD and increments version in this same transaction,
+ // including writes from sync. Operational-only writes do not create history.
+ const updated = fields.length ? (await client.query(
+ `UPDATE memories SET ${fields.join(', ')} WHERE id = $${params.length + 1} RETURNING *`,
+ [...params, id]
+ )).rows[0] : row;
+ if (updates.relatedMemories) {
+ // Legacy edits replace only the symmetric relation; preserve typed provenance.
+ await client.query("DELETE FROM memory_links WHERE source_id = $1 AND link_type = 'related'", [id]);
+ if (updates.relatedMemories.length) {
+ const slots = updates.relatedMemories.map((_, i) => `($1, $${i + 2})`).join(', ');
+ await client.query(`INSERT INTO memory_links (source_id, target_id) VALUES ${slots} ON CONFLICT DO NOTHING`,
+ [id, ...updates.relatedMemories]);
}
- const links = await client.query('SELECT target_id FROM memory_links WHERE source_id = $1', [id]);
- return { ...rowToMemory(updated), relatedMemories: links.rows.map(link => link.target_id) };
- });
+ await client.query('UPDATE memories SET updated_at = NOW() WHERE id = $1', [id]);
+ }
+ const links = await client.query('SELECT target_id FROM memory_links WHERE source_id = $1', [id]);
+ return { ...rowToMemory(updated), relatedMemories: links.rows.map(link => link.target_id) };
+}
+
+export async function updateMemory(id, updates) {
+ const memory = await withTransaction(client => updateMemoryWithClient(client, id, updates));
if (!memory) return null;
console.log(`🧠 Memory updated: ${id}`);