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

10.4 KB
Raw Blame
import { z } from 'zod';
import { partialWithoutDefaults } from './zodCompat.js';
import { MEMORY_LINK_TYPES } from './memoryLinkTypes.js';

// Memory ids are directory names in the file-backed store. Keep route input
// constrained to one plain path segment before it reaches any filesystem code.
export const memoryIdSchema = z.string().regex(/^[A-Za-z0-9._-]+$/);
export const memoryIdParamSchema = z.object({ id: memoryIdSchema });

// Memory types enum
export const memoryTypeEnum = z.enum([
  'fact',
  'learning',
  'observation',
  'decision',
  'preference',
  'context'
]);

// Memory status enum
export const memoryStatusEnum = z.enum(['active', 'archived', 'expired', 'pending_approval']);

// Memory category enum (extensible, but common ones)
export const memoryCategoryEnum = z.enum([
  'codebase',
  'workflow',
  'tools',
  'architecture',
  'patterns',
  'conventions',
  'preferences',
  'system',
  'project',
  'other'
]);

// Core memory schema for creation
export const memoryCreateSchema = z.object({
  type: memoryTypeEnum,
  content: z.string().min(1).max(10240),
  summary: z.string().max(500).optional(),
  category: z.string().min(1).max(100).optional().default('other'),
  tags: z.array(z.string().max(50)).max(20).optional().default([]),
  confidence: z.number().min(0).max(1).optional().default(0.8),
  importance: z.number().min(0).max(1).optional().default(0.5),
  relatedMemories: z.array(z.string().guid()).optional().default([]),
  sourceTaskId: z.string().optional(),
  sourceAgentId: z.string().optional(),
  sourceAppId: z.string().nullable().optional()
});

// Full memory schema (includes system-generated fields)
export const memorySchema = memoryCreateSchema.extend({
  id: z.string().guid(),
  embedding: z.array(z.number()).optional(),
  embeddingModel: z.string().optional(),
  accessCount: z.number().int().min(0).default(0),
  lastAccessed: z.string().datetime().optional(),
  createdAt: z.string().datetime(),
  updatedAt: z.string().datetime(),
  expiresAt: z.string().datetime().nullable().optional(),
  status: memoryStatusEnum.default('active')
});

// Partial schema for updates
export const memoryUpdateSchema = partialWithoutDefaults(memoryCreateSchema).extend({
  status: memoryStatusEnum.optional(),
  expectedVersion: z.number().int().positive().optional(),
  changedBy: z.string().trim().min(1).max(100).optional(),
  changeReason: z.string().max(2000).optional()
});

// Search query schema
export const memorySearchSchema = z.object({
  query: z.string().min(1).max(1000),
  types: z.array(memoryTypeEnum).optional(),
  categories: z.array(z.string()).optional(),
  tags: z.array(z.string()).optional(),
  status: memoryStatusEnum.optional().default('active'),
  appId: z.string().max(100).optional(),
  minRelevance: z.number().min(0).max(1).optional().default(0.7),
  limit: z.number().int().min(1).max(100).optional().default(20),
  offset: z.number().int().min(0).optional().default(0)
});

// ---------------------------------------------------------------------------
// Query-string coercion
//
// The list/timeline schemas below validate `req.query`, where every value
// arrives as a string: arrays are comma-separated (`?types=fact,learning`, the
// shape `client/src/services/apiMemory.js` sends) and numbers are digits. These
// preprocessors accept both the query form and the already-parsed form so the
// same schema still validates a JSON body. An empty param (`?types=`) becomes
// `undefined` — "not filtered" — rather than an empty list or a NaN.
// ---------------------------------------------------------------------------

const csvList = (inner) => z.preprocess((v) => {
  if (typeof v !== 'string') return v;
  const parts = v.split(',').map((s) => s.trim()).filter(Boolean);
  return parts.length > 0 ? parts : undefined;
}, inner);

const numeric = (inner) => z.preprocess((v) => {
  if (typeof v !== 'string') return v;
  const trimmed = v.trim();
  if (trimmed === '') return undefined;
  const parsed = Number(trimmed);
  return Number.isFinite(parsed) ? parsed : v;
}, inner);

const emptyToUndefined = (inner) => z.preprocess(
  (v) => (typeof v === 'string' && v.trim() === '' ? undefined : v),
  inner
);

// A `YYYY-MM-DD` string can match the shape and still name a day that doesn't
// exist (`2026-02-30`). `Date.parse` rolls those over instead of failing, so
// round-trip the parts — otherwise Postgres is the one that rejects the date,
// as a 500 rather than a 400.
const isRealCalendarDate = (v) => {
  const [year, month, day] = v.split('-').map(Number);
  const parsed = new Date(Date.UTC(year, month - 1, day));
  // Date.UTC maps a 0-99 year onto 1900-1999; re-set it so a year like 0026
  // compares against itself rather than 1926.
  parsed.setUTCFullYear(year);
  return parsed.getUTCFullYear() === year
    && parsed.getUTCMonth() === month - 1
    && parsed.getUTCDate() === day;
};

// `startDate`/`endDate` reach Postgres as `created_at >= $n` bind params, so a
// bare calendar date is as usable as a full timestamp — accept either. The
// datetime branch allows a `+HH:MM` offset, not just a `Z` suffix, since either
// is a legitimate serialization of the same instant. A bare date means midnight
// at both ends of the range, matching how these bounds have always been read —
// pass a full timestamp to include part of a day.
const dateBoundary = z.union([
  z.string().datetime({ offset: true }),
  z.string()
    .regex(/^\d{4}-\d{2}-\d{2}$/, 'must be an ISO datetime or YYYY-MM-DD date')
    .refine(isRealCalendarDate, 'must be a real calendar date')
]);

// List/filter query schema (GET /api/memory — validated against req.query).
// `limit` caps at 500 to match the timeline schema and the ceiling this route
// has always enforced via parsePagination's maxLimit.
export const memoryListSchema = z.object({
  types: csvList(z.array(memoryTypeEnum).optional()),
  categories: csvList(z.array(z.string().max(100)).optional()),
  tags: csvList(z.array(z.string().max(50)).optional()),
  status: emptyToUndefined(memoryStatusEnum.optional().default('active')),
  appId: emptyToUndefined(z.string().max(100).optional()),
  sourceAgentId: emptyToUndefined(z.string().max(128).optional()),
  limit: numeric(z.number().int().min(1).max(500).optional().default(50)),
  offset: numeric(z.number().int().min(0).optional().default(0)),
  sortBy: emptyToUndefined(z.enum(['createdAt', 'updatedAt', 'importance', 'accessCount']).optional().default('createdAt')),
  sortOrder: emptyToUndefined(z.enum(['asc', 'desc']).optional().default('desc'))
});

// Timeline query schema (GET /api/memory/timeline — validated against req.query)
export const memoryTimelineSchema = z.object({
  startDate: emptyToUndefined(dateBoundary.optional()),
  endDate: emptyToUndefined(dateBoundary.optional()),
  types: csvList(z.array(memoryTypeEnum).optional()),
  // Both timeline backends filter on appId (including the `__not_brain`
  // sentinel the CoS Memory tab uses); it was unreachable while the handler
  // hand-built its options object.
  appId: emptyToUndefined(z.string().max(100).optional()),
  limit: numeric(z.number().int().min(1).max(500).optional().default(100))
});

// Memory extraction request schema (from agent output)
export const memoryExtractSchema = z.object({
  agentId: z.string(),
  taskId: z.string(),
  output: z.string().min(1)
});

// Memory consolidation request schema
export const memoryConsolidateSchema = z.object({
  similarityThreshold: z.number().min(0.5).max(1).optional().default(0.9),
  dryRun: z.boolean().optional().default(false),
  reason: z.string().max(2000).optional()
});

// Decay request schema — 0.02 is 2x the shipped default; higher rates purge rather than tune
export const memoryDecaySchema = z.object({
  decayRate: z.number().positive().max(0.02).optional().default(0.01)
}).strict();

// Link memories request schema
export const memoryLinkSchema = z.object({
  sourceId: z.string().guid(),
  targetId: z.string().guid(),
  // Omitted means the legacy symmetric 'related' link, so older clients keep working.
  linkType: z.enum(MEMORY_LINK_TYPES).optional(),
  note: z.string().max(2000).optional(),
  createdBy: z.string().trim().min(1).max(100).optional()
}).refine(
  (v) => v.sourceId !== v.targetId || (v.linkType ?? 'related') === 'related',
  { message: 'A directed link needs two different memories', path: ['targetId'] }
);

// Single sync memory item schema (incoming from remote peer)
const syncMemoryItemSchema = z.object({
  id: z.string().guid(),
  type: memoryTypeEnum,
  content: z.string().min(1).max(10240),
  summary: z.string().max(500).nullable().optional(),
  category: z.string().max(100).nullable().optional(),
  tags: z.array(z.string().max(50)).optional().default([]),
  embedding: z.array(z.number()).length(768).nullable().optional(),
  embeddingModel: z.string().max(200).nullable().optional(),
  confidence: z.number().min(0).max(1).nullable().optional(),
  importance: z.number().min(0).max(1).nullable().optional(),
  status: memoryStatusEnum.optional().default('active'),
  sourceTaskId: z.string().nullable().optional(),
  sourceAgentId: z.string().nullable().optional(),
  sourceAppId: z.string().nullable().optional(),
  expiresAt: z.string().datetime().nullable().optional(),
  createdAt: z.string().datetime(),
  updatedAt: z.string().datetime(),
  originInstanceId: z.string().max(36).nullable().optional(),
  version: z.number().int().positive().optional(),
  syncSequence: z.string().regex(/^\d+$/).optional()
});

// Sync request body schema
export const memorySyncSchema = z.object({
  memories: z.array(syncMemoryItemSchema).max(1000),
  schemaVersion: z.number().int().nonnegative().optional()
});

// History is local. The wire version is an explicit receiver capability.
export const memoryVersionQuerySchema = z.object({
  version: z.coerce.number().int().positive().optional()
});
export const memoryVersionsQuerySchema = z.object({
  limit: z.coerce.number().int().min(1).max(100).default(20),
  offset: z.coerce.number().int().min(0).default(0)
});
export const memoryRetireSchema = z.object({
  reason: z.string().max(2000).optional(),
  supersededBy: z.string().guid().optional()
});
export const memoryDeleteQuerySchema = memoryRetireSchema.extend({
  hard: z.enum(['true', 'false']).default('false')
});

export const memorySyncQuerySchema = z.object({
  since: z.string().regex(/^\d+$/).default('0'),
  limit: z.coerce.number().int().min(1).transform(value => Math.min(value, 1000)).default(100),
  schemaVersion: z.coerce.number().int().nonnegative().optional()
});