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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Memory Backend Switcher
*
* Selects the PostgreSQL backend (memoryDB.js) for normal installs. PostgreSQL
* is mandatory; when MEMORY_BACKEND is unset we require a healthy DB and do NOT
* silently fall back to file storage — an unavailable DB throws. The file
* backend (memory.js) is reachable only via the explicit MEMORY_BACKEND=file
* escape hatch or a test runner (both unsupported for production).
*
* Usage:
* import * as memory from './memoryBackend.js';
* // All functions are the same regardless of backend
*/
import { isTestRunner } from '../lib/runtimeEnv.js';
import { checkHealth, ensureSchema } from '../lib/db.js';
import { DEFAULT_MEMORY_CONFIG } from './memoryConfig.js';
export { DEFAULT_MEMORY_CONFIG };
let backend = null;
let backendName = null;
/**
* Initialize and return the appropriate backend module.
* Caches the result after first call.
*/
async function getBackend() {
if (backend) return backend;
const envBackend = process.env.MEMORY_BACKEND;
// `MEMORY_BACKEND=file` is an explicit, UNSUPPORTED-for-production escape
// hatch — honored for development/tests only. PostgreSQL is the mandatory
// backend for normal installs (the creative catalog has no file-backed
// equivalent). See docs/plans/2026-06-06-create-postgres-storage-inventory.md.
if (envBackend === 'file') {
backend = await import('./memory.js');
backendName = 'file';
console.log('🧠 Memory backend: file-based (JSON) — explicit MEMORY_BACKEND=file (unsupported for production)');
return backend;
}
if (envBackend === 'postgres') {
await ensureSchema();
backend = await import('./memoryDB.js');
backendName = 'postgres';
console.log('🧠 Memory backend: PostgreSQL + pgvector');
return backend;
}
// Under the test runner, ALWAYS use the file backend — never probe or touch a
// real Postgres instance. A developer's machine commonly has a live `portos`
// DB running (and that DB is federated to real peers). If the suite were to
// auto-detect that healthy DB it would write hundreds of fixture
// universes/series into it AND fan them out to live peers via
// autoSubscribeRecordToAllPeers — and test-cleanup tombstones would delete the
// user's real records. This must short-circuit BEFORE checkHealth(); the
// earlier conditional-on-unavailable form silently wrote to a dev's real DB
// whenever Postgres happened to be up. An explicit `MEMORY_BACKEND=postgres`
// (handled above) still opts a suite into the PG path.
if (isTestRunner()) {
backend = await import('./memory.js');
backendName = 'file';
console.log('🧠 Memory backend: file-based (test mode — Postgres deliberately bypassed)');
return backend;
}
// MEMORY_BACKEND unset: require PostgreSQL. We do NOT silently fall back to
// file storage when Postgres is unavailable — that masks a broken install.
const health = await checkHealth();
if (health.connected && health.hasSchema) {
await ensureSchema();
backend = await import('./memoryDB.js');
backendName = 'postgres';
console.log('🧠 Memory backend: PostgreSQL + pgvector (auto-detected)');
return backend;
}
// Production / normal install with no DB and no escape hatch: this is an
// error condition, not a fallback. Log loudly and point at setup. Startup
// (server/index.js) fails fast on the same condition.
console.error(`❌ Memory backend unavailable: PostgreSQL is required but ${health.connected ? 'the schema is missing' : `unreachable (${health.error || 'connection failed'})`}`);
console.error(' PostgreSQL is a mandatory dependency for PortOS. Set it up with: npm run setup:db');
console.error(' Dev/test only: set PGMODE=file in .env (the launcher maps it to MEMORY_BACKEND=file) to use the (unsupported) file backend.');
throw new Error('PostgreSQL is required for the memory backend — run `npm run setup:db`');
}
/**
* Ensure the backend is initialized and return its name.
* Safe to call from routes that need the backend name before any other function.
*/
export async function ensureBackend() {
await getBackend();
return backendName;
}
/**
* Get the name of the active backend (null if not yet initialized)
*/
export function getBackendName() {
return backendName;
}
// Re-export all functions with lazy initialization
// Each function loads the backend on first call, then delegates
export async function createMemory(data, embedding) {
const b = await getBackend();
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();
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) {
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);
}
export async function getMemory(id) {
const b = await getBackend();
return b.getMemory(id);
}
export async function getMemories(options) {
const b = await getBackend();
return b.getMemories(options);
}
export async function countMemories(options) {
const b = await getBackend();
return b.countMemories(options);
}
export async function updateMemory(id, updates) {
const b = await getBackend();
return b.updateMemory(id, updates);
}
export async function updateMemoryEmbedding(id, embedding) {
const b = await getBackend();
return b.updateMemoryEmbedding(id, embedding);
}
export async function archiveMemory(id, options) {
const b = await getBackend();
return b.archiveMemory(id, options);
}
export async function purgeMemory(id) {
const b = await getBackend();
return b.purgeMemory(id);
}
/** @deprecated Call archiveMemory or purgeMemory so the call site says whether it destroys data. */
export async function deleteMemory(id, hard) {
return hard ? purgeMemory(id) : archiveMemory(id);
}
export async function approveMemory(id) {
const b = await getBackend();
return b.approveMemory(id);
}
export async function rejectMemory(id, options) {
const b = await getBackend();
return b.rejectMemory(id, options);
}
export async function searchMemories(queryEmbedding, options) {
const b = await getBackend();
return b.searchMemories(queryEmbedding, options);
}
export async function hybridSearchMemories(query, queryEmbedding, options) {
const b = await getBackend();
return b.hybridSearchMemories(query, queryEmbedding, options);
}
export async function rebuildBM25Index() {
const b = await getBackend();
return b.rebuildBM25Index();
}
export async function getBM25Stats() {
const b = await getBackend();
return b.getBM25Stats();
}
export async function getTimeline(options) {
const b = await getBackend();
return b.getTimeline(options);
}
export async function getCategories() {
const b = await getBackend();
return b.getCategories();
}
export async function getTags() {
const b = await getBackend();
return b.getTags();
}
export async function getRelatedMemories(id, limit) {
const b = await getBackend();
return b.getRelatedMemories(id, limit);
}
// `options.sourceIds` (internal): absent → the full CoS graph; an array (even
// empty) → only nodes/edges inside that memory-id scope (#10953).
export async function getGraphData(options) {
const b = await getBackend();
return b.getGraphData(options);
}
export async function getMemoryIdsMissingEmbedding() {
const b = await getBackend();
return b.getMemoryIdsMissingEmbedding();
}
export async function linkMemories(sourceId, targetId, options) {
const b = await getBackend();
return b.linkMemories(sourceId, targetId, options);
}
export async function consolidateMemories(threshold, dryRun, options) {
const b = await getBackend();
return b.consolidateMemories(threshold, dryRun, options);
}
export async function applyDecay(decayRate) {
const b = await getBackend();
return b.applyDecay(decayRate);
}
export async function clearExpired() {
const b = await getBackend();
return b.clearExpired();
}
export async function getStats() {
const b = await getBackend();
return b.getStats();
}
export function invalidateCaches() {
if (backend) backend.invalidateCaches();
}
export async function flushBM25Index() {
const b = await getBackend();
return b.flushBM25Index();
}
export async function getMemoryVersions(id, options) {
const b = await getBackend();
return b.getMemoryVersions ? b.getMemoryVersions(id, options) : [];
}
export async function getMemoryVersion(id, version) {
const b = await getBackend();
return b.getMemoryVersion ? b.getMemoryVersion(id, version) : null;
}