@saluzi/saluzi-edu 0.7.4 → 0.7.6

package/packages/remote-control-server/src/services/memories.ts

@@ -0,0 +1,747 @@
+import { nanoid } from 'nanoid'
+import type { Database } from 'bun:sqlite'
+import { error as logError, log } from '../logger'
+import { getDb } from '../db/sqlite'
+import { publishSessionEvent } from './transport'
+
+/**
+ * Memories — durable team/personal memory entries.
+ *
+ * Two first-class scopes, discriminated by `scope_kind`:
+ * - personal: `owner_user_id`, strictly private — visible only to the owner
+ *   (not even system admins browse it in listings; admin bypass is limited
+ *   to manage operations and pack assembly, mirroring the "private means
+ *   private" TDAM semantics).
+ * - team: `team_id`, visible to every active team member.
+ *
+ * Sessions are NOT a first-class scope. `source_session_id` is a provenance
+ * link ("this memory was distilled from that session") and an optional
+ * recall filter — never a registration gate (TDAM task-optional lesson).
+ */
+
+export const MEMORY_TYPES = [
+  'user',
+  'feedback',
+  'project',
+  'reference',
+] as const
+export type MemoryType = (typeof MEMORY_TYPES)[number]
+
+export const MEMORY_LAYERS = ['episodic', 'semantic', 'procedural'] as const
+export type MemoryLayer = (typeof MEMORY_LAYERS)[number]
+
+export type MemoryScopeKind = 'personal' | 'team'
+
+export interface MemoryRow {
+  id: string
+  scope_kind: MemoryScopeKind
+  owner_user_id: string | null
+  team_id: string | null
+  name: string
+  description: string | null
+  type: MemoryType
+  layer: MemoryLayer
+  content: string
+  status: 'active' | 'superseded' | 'archived'
+  source_session_id: string | null
+  version: number
+  created_by: string | null
+  created_at: string
+  updated_at: string
+}
+
+export type MemoryMeta = Omit<MemoryRow, 'content'>
+
+/** Pack payload handed to the bridge: rel path → file content. */
+export interface MemoryPack {
+  files: Record<string, string>
+}
+
+export class MemoryError extends Error {
+  code: string
+  constructor(code: string, message: string) {
+    super(message)
+    this.name = 'MemoryError'
+    this.code = code
+  }
+}
+
+function nowIso(): string {
+  return new Date().toISOString()
+}
+
+function toMeta(row: MemoryRow): MemoryMeta {
+  const { content: _content, ...meta } = row
+  return meta
+}
+
+/** FTS5 write — insert on create, delete+insert on update (id-stable). */
+function upsertFts(db: Database, row: MemoryRow): void {
+  try {
+    db.query('DELETE FROM memories_fts WHERE memory_id = $id').run({
+      $id: row.id,
+    })
+    db.query(
+      `INSERT INTO memories_fts (name, description, content, memory_id)
+       VALUES ($name, $description, $content, $id)`,
+    ).run({
+      $name: row.name,
+      $description: row.description ?? '',
+      $content: row.content,
+      $id: row.id,
+    })
+  } catch (err) {
+    // FTS is an accelerator, not a source of truth — a failed index write
+    // must not break the memory write itself.
+    logError(`[memories] fts upsert failed id=${row.id}:`, err)
+  }
+}
+
+function removeFts(db: Database, id: string): void {
+  try {
+    db.query('DELETE FROM memories_fts WHERE memory_id = $id').run({ $id: id })
+  } catch (err) {
+    logError(`[memories] fts delete failed id=${id}:`, err)
+  }
+}
+
+function getMemoryRowInner(db: Database, id: string): MemoryRow | null {
+  const row = db
+    .query('SELECT * FROM memories WHERE id = $id')
+    .get({ $id: id }) as MemoryRow | null
+  return row ?? null
+}
+
+/** Fetch a memory; archived rows read as missing (soft delete). */
+export function getMemoryRow(id: string): MemoryRow | null {
+  try {
+    const row = getMemoryRowInner(getDb(), id)
+    if (!row || row.status === 'archived') return null
+    return row
+  } catch (err) {
+    logError(`[memories] getMemoryRow failed id=${id}:`, err)
+    return null
+  }
+}
+
+export interface CreateMemoryParams {
+  scopeKind: MemoryScopeKind
+  ownerUserId?: string
+  teamId?: string
+  name: string
+  description?: string
+  type: MemoryType
+  content: string
+  layer?: MemoryLayer
+  sourceSessionId?: string
+  createdBy?: string
+}
+
+export function createMemory(params: CreateMemoryParams): MemoryRow {
+  const db = getDb()
+
+  const name = params.name.trim()
+  if (!name) throw new MemoryError('invalid_name', 'name is required')
+  if (!params.content.trim()) {
+    throw new MemoryError('invalid_content', 'content is required')
+  }
+  if (!MEMORY_TYPES.includes(params.type)) {
+    throw new MemoryError(
+      'invalid_type',
+      `type must be one of ${MEMORY_TYPES.join(', ')}`,
+    )
+  }
+
+  const now = nowIso()
+  const id = nanoid(21)
+  const ownerUserId =
+    params.scopeKind === 'personal' ? (params.ownerUserId ?? null) : null
+  const teamId = params.scopeKind === 'team' ? (params.teamId ?? null) : null
+
+  try {
+    db.query(
+      `INSERT INTO memories
+         (id, scope_kind, owner_user_id, team_id, name, description, type,
+          layer, content, status, source_session_id, version, created_by,
+          created_at, updated_at)
+       VALUES ($id, $scope_kind, $owner_user_id, $team_id, $name, $description,
+               $type, $layer, $content, 'active', $source_session_id, 1,
+               $created_by, $now, $now)`,
+    ).run({
+      $id: id,
+      $scope_kind: params.scopeKind,
+      $owner_user_id: ownerUserId,
+      $team_id: teamId,
+      $name: name,
+      $description: params.description?.trim() || null,
+      $type: params.type,
+      $layer: params.layer ?? 'semantic',
+      $content: params.content,
+      $source_session_id: params.sourceSessionId ?? null,
+      $created_by: params.createdBy ?? null,
+      $now: now,
+    })
+  } catch (err) {
+    // CHECK violation (missing owner column) or similar — surface as typed error.
+    throw new MemoryError(
+      'invalid_scope',
+      `createMemory failed: ${err instanceof Error ? err.message : String(err)}`,
+    )
+  }
+
+  const row = getMemoryRowInner(db, id)
+  if (!row)
+    throw new MemoryError('insert_failed', 'memory row missing after insert')
+  upsertFts(db, row)
+  return row
+}
+
+function isTeamMember(db: Database, userId: string, teamId: string): boolean {
+  const row = db
+    .query(
+      'SELECT 1 FROM team_members WHERE team_id = $teamId AND user_id = $userId LIMIT 1',
+    )
+    .get({ $teamId: teamId, $userId: userId })
+  return !!row
+}
+
+/**
+ * Visibility check. Order (TDAM permission-checker pattern):
+ * resource exists → personal: owner only (strictly private — admin listings
+ * don't include others' personal rows, and the single-fetch path keeps the
+ * same semantics for consistency) → team: active membership → deny.
+ */
+export function isMemoryVisibleToUser(
+  id: string,
+  userId: string,
+  isAdmin = false,
+): boolean {
+  const db = getDb()
+  const row = getMemoryRow(id)
+  if (!row) return false
+
+  if (row.scope_kind === 'personal') {
+    return row.owner_user_id === userId
+  }
+  // Team scope — membership grants read; system admin too.
+  if (isAdmin) return true
+  return isTeamMember(db, userId, row.team_id!)
+}
+
+/**
+ * Manage = edit/delete/promote. System admin, personal owner,
+ * team row creator, or team owner/admin (managing other members' rows).
+ */
+export function canManageMemory(
+  id: string,
+  userId: string,
+  isAdmin = false,
+): boolean {
+  const db = getDb()
+  const row = getMemoryRow(id)
+  if (!row) return false
+  if (isAdmin) return true
+
+  if (row.scope_kind === 'personal') {
+    return row.owner_user_id === userId
+  }
+  if (row.created_by === userId) return true
+  const member = db
+    .query(
+      `SELECT role FROM team_members
+       WHERE team_id = $teamId AND user_id = $userId LIMIT 1`,
+    )
+    .get({ $teamId: row.team_id!, $userId: userId }) as { role: string } | null
+  return !!member && (member.role === 'owner' || member.role === 'admin')
+}
+
+export interface ListMemoriesFilter {
+  teamId?: string
+  /** Personal space — rows owned by the caller across all teams. */
+  personalScope?: boolean
+  sessionId?: string
+  type?: MemoryType
+}
+
+/**
+ * List memories visible to a user. Permission filtering happens BEFORE the
+ * row cap so the result never leaks cross-team rows (caller-scoped lists,
+ * TDAM lesson: filter first, then paginate).
+ *
+ * Admins see team rows across teams but never others' personal rows —
+ * personal scope is owner-only by construction.
+ */
+export function listMemoriesForUser(
+  userId: string,
+  filter: ListMemoriesFilter = {},
+  isAdmin = false,
+): MemoryMeta[] {
+  const db = getDb()
+  const conditions: string[] = [`status != 'archived'`]
+  const params: Record<string, string> = {}
+
+  if (filter.teamId) {
+    conditions.push("scope_kind = 'team' AND team_id = $teamId")
+    params.$teamId = filter.teamId
+  } else if (filter.personalScope) {
+    conditions.push("scope_kind = 'personal' AND owner_user_id = $userId")
+    params.$userId = userId
+  }
+  if (filter.sessionId) {
+    conditions.push('source_session_id = $sessionId')
+    params.$sessionId = filter.sessionId
+  }
+  if (filter.type) {
+    conditions.push('type = $type')
+    params.$type = filter.type
+  }
+
+  let rows: MemoryRow[] = []
+  try {
+    rows = db
+      .query(
+        `SELECT * FROM memories WHERE ${conditions.join(' AND ')}
+         ORDER BY updated_at DESC LIMIT 500`,
+      )
+      .all(params) as unknown as MemoryRow[]
+  } catch (err) {
+    logError('[memories] listMemoriesForUser failed:', err)
+    return []
+  }
+
+  if (isAdmin && !filter.personalScope) {
+    return rows.filter(r => r.scope_kind === 'team').map(toMeta)
+  }
+  return rows
+    .filter(row => isMemoryVisibleToUser(row.id, userId, isAdmin))
+    .map(toMeta)
+}
+
+export interface UpdateMemoryParams {
+  name?: string
+  description?: string
+  content?: string
+  type?: MemoryType
+  layer?: MemoryLayer
+}
+
+/** Edit an existing memory. Bumps version and refreshes FTS. */
+export function updateMemory(
+  id: string,
+  params: UpdateMemoryParams,
+): MemoryRow | null {
+  const db = getDb()
+  const row = getMemoryRowInner(db, id)
+  if (!row || row.status === 'archived') return null
+
+  const name = params.name?.trim() || row.name
+  const description =
+    params.description !== undefined
+      ? params.description.trim() || null
+      : row.description
+  const content = params.content ?? row.content
+  if (!content.trim()) {
+    throw new MemoryError('invalid_content', 'content is required')
+  }
+  const type = params.type ?? row.type
+  if (!MEMORY_TYPES.includes(type)) {
+    throw new MemoryError(
+      'invalid_type',
+      `type must be one of ${MEMORY_TYPES.join(', ')}`,
+    )
+  }
+  const layer = params.layer ?? row.layer
+
+  db.query(
+    `UPDATE memories
+     SET name = $name, description = $description, content = $content,
+         type = $type, layer = $layer, version = version + 1, updated_at = $now
+     WHERE id = $id`,
+  ).run({
+    $id: id,
+    $name: name,
+    $description: description,
+    $content: content,
+    $type: type,
+    $layer: layer,
+    $now: nowIso(),
+  })
+
+  const updated = getMemoryRowInner(db, id)
+  if (updated) upsertFts(db, updated)
+  return updated
+}
+
+/** Soft delete — archived reads as missing everywhere. */
+export function archiveMemory(id: string): boolean {
+  const db = getDb()
+  try {
+    const result = db
+      .query(
+        `UPDATE memories SET status = 'archived', updated_at = $now
+         WHERE id = $id AND status != 'archived'`,
+      )
+      .run({ $id: id, $now: nowIso() })
+    const changed = (result as unknown as { changes?: number }).changes === 1
+    if (changed) removeFts(db, id)
+    return changed
+  } catch (err) {
+    logError(`[memories] archiveMemory failed id=${id}:`, err)
+    return false
+  }
+}
+
+/**
+ * Promote a personal memory to team scope. Only the owner may promote their
+ * own memory, and they must be a member of the target team. The move keeps
+ * provenance (created_by, source_session_id) and bumps the version.
+ */
+export function promoteMemoryToTeam(
+  id: string,
+  userId: string,
+  teamId: string,
+): MemoryRow {
+  const db = getDb()
+  const row = getMemoryRowInner(db, id)
+  if (!row || row.status === 'archived') {
+    throw new MemoryError('not_found', 'Memory not found')
+  }
+  if (row.scope_kind !== 'personal') {
+    throw new MemoryError(
+      'not_personal',
+      'Only personal memories can be promoted',
+    )
+  }
+  if (row.owner_user_id !== userId) {
+    throw new MemoryError('forbidden', 'Only the owner can promote this memory')
+  }
+  if (!isTeamMember(db, userId, teamId)) {
+    throw new MemoryError('forbidden', 'Not a member of the target team')
+  }
+
+  db.query(
+    `UPDATE memories
+     SET scope_kind = 'team', owner_user_id = NULL, team_id = $teamId,
+         version = version + 1, updated_at = $now
+     WHERE id = $id`,
+  ).run({ $id: id, $teamId: teamId, $now: nowIso() })
+
+  const updated = getMemoryRowInner(db, id)
+  if (!updated) throw new MemoryError('update_failed', 'promote failed')
+  upsertFts(db, updated)
+  return updated
+}
+
+// --- Memory pack (injection) ---------------------------------------------
+//
+// Compiles the stable-zone memory pack for a session: the primary user
+// owner's personal memories plus, when the session is team-owned, the
+// team's memories. Layout mirrors the CLI memdir conventions so the child
+// process's existing loadMemoryPrompt machinery works unchanged:
+//
+//   MEMORY.md            — index, one line per entry (≤150 chars, ≤200 lines)
+//   <type>_<slug>.md     — personal memory files, memdir frontmatter format
+//   team/                — team memories (memdir team subdir layout)
+
+const PACK_MAX_LINES = 200
+const PACK_LINE_MAX_CHARS = 150
+
+function slugifyName(name: string): string {
+  const slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9\u4e00-\u9fff]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return slug || 'memory'
+}
+
+function memoryFileContent(row: MemoryRow): string {
+  return [
+    '---',
+    `name: ${row.name}`,
+    `description: ${row.description ?? row.name}`,
+    `type: ${row.type}`,
+    '---',
+    '',
+    row.content,
+    '',
+  ].join('\n')
+}
+
+function packLine(row: MemoryRow, relPath: string): string {
+  const hook = row.description ?? row.name
+  const line = `- [${row.name}](${relPath}) — ${hook}`
+  return line.length > PACK_LINE_MAX_CHARS
+    ? `${line.slice(0, PACK_LINE_MAX_CHARS - 1)}…`
+    : line
+}
+
+function buildPackFromRows(rows: MemoryRow[]): MemoryPack {
+  const files: Record<string, string> = {}
+  const lines: string[] = []
+  const used = new Set<string>()
+
+  for (const row of rows) {
+    const teamPrefix = row.scope_kind === 'team' ? 'team/' : ''
+    let rel = `${teamPrefix}${row.type}_${slugifyName(row.name)}.md`
+    // Dedupe colliding paths deterministically.
+    if (used.has(rel))
+      rel = `${teamPrefix}${row.type}_${slugifyName(row.name)}-${row.id}.md`
+    used.add(rel)
+    files[rel] = memoryFileContent(row)
+    lines.push(packLine(row, rel))
+  }
+
+  const capped = lines.slice(0, PACK_MAX_LINES)
+  if (lines.length > capped.length) {
+    capped.push(`- … ${lines.length - capped.length} more memories omitted`)
+  }
+  files['MEMORY.md'] = `${capped.join('\n')}\n`
+  return { files }
+}
+
+/** Resolve the identity context for a session: primary user owner + team owner. */
+function resolveSessionMemoryScope(
+  db: Database,
+  sessionId: string,
+): { userId: string | null; teamId: string | null } {
+  try {
+    const owners = db
+      .query(
+        `SELECT owner_type, owner_id FROM session_owners WHERE session_id = $sid`,
+      )
+      .all({ $sid: sessionId }) as unknown as {
+      owner_type: string
+      owner_id: string
+    }[]
+    const userId = owners.find(o => o.owner_type === 'user')?.owner_id ?? null
+    const teamId = owners.find(o => o.owner_type === 'team')?.owner_id ?? null
+    return { userId, teamId }
+  } catch (err) {
+    logError(
+      `[memories] resolveSessionMemoryScope failed session=${sessionId}:`,
+      err,
+    )
+    return { userId: null, teamId: null }
+  }
+}
+
+function activePersonalMemories(db: Database, userId: string): MemoryRow[] {
+  return db
+    .query(
+      `SELECT * FROM memories
+       WHERE scope_kind = 'personal' AND owner_user_id = $uid AND status = 'active'
+       ORDER BY updated_at DESC LIMIT 100`,
+    )
+    .all({ $uid: userId }) as unknown as MemoryRow[]
+}
+
+function activeTeamMemories(db: Database, teamId: string): MemoryRow[] {
+  return db
+    .query(
+      `SELECT * FROM memories
+       WHERE scope_kind = 'team' AND team_id = $tid AND status = 'active'
+       ORDER BY updated_at DESC LIMIT 100`,
+    )
+    .all({ $tid: teamId }) as unknown as MemoryRow[]
+}
+
+/**
+ * Compile the injection pack for a session. Personal memories of the
+ * session's primary user owner; team memories only when the session is
+ * team-owned. Empty pack when the session has no user owner.
+ */
+export function buildMemoryPack(sessionId: string): MemoryPack {
+  const db = getDb()
+  const { userId, teamId } = resolveSessionMemoryScope(db, sessionId)
+  if (!userId) return { files: {} }
+
+  const rows = activePersonalMemories(db, userId)
+  if (teamId) rows.push(...activeTeamMemories(db, teamId))
+  return buildPackFromRows(rows)
+}
+
+// --- Write-back (agent → store) -------------------------------------------
+
+export interface MemoryWriteBackEntry {
+  rel_path: string
+  content: string
+}
+
+export interface SyncMemoriesResult {
+  created: number
+  updated: number
+  skipped: number
+}
+
+/**
+ * Ingest write-back entries from a bridge worker. Identity is derived from
+ * the session (owner_user_id) — caller-supplied owner/team fields are
+ * ignored by design (anti-forgery, TDAM memory-bridge lesson). Entries land
+ * in the owner's personal scope with source_session_id provenance.
+ *
+ * Dedup: FTS recall over the owner's active personal memories by name;
+ * a hit updates the existing row (content replace, version bump) instead
+ * of inserting a near-duplicate.
+ */
+export function syncMemories(
+  sessionId: string,
+  entries: MemoryWriteBackEntry[],
+): SyncMemoriesResult {
+  const db = getDb()
+  const { userId } = resolveSessionMemoryScope(db, sessionId)
+  if (!userId) {
+    throw new MemoryError(
+      'no_owner',
+      'Session has no user owner to attribute memories to',
+    )
+  }
+
+  const result: SyncMemoriesResult = { created: 0, updated: 0, skipped: 0 }
+
+  for (const entry of entries) {
+    const rel = entry.rel_path
+    // Gate 1: skip working-layer scratch, dotfiles, non-markdown, and the
+    // injected team/ subtree. Team memories were materialized INTO the pack;
+    // a child edit to them must not fork a silent personal copy (team
+    // memories change through the web UI / promote flow, never write-back).
+    if (
+      rel === 'MEMORY.md' ||
+      rel === 'team/MEMORY.md' ||
+      rel.startsWith('team/') ||
+      rel.startsWith('.working/') ||
+      rel.includes('/.working/') ||
+      (rel.split('/').pop() ?? '').startsWith('.') ||
+      !rel.endsWith('.md')
+    ) {
+      result.skipped++
+      continue
+    }
+
+    const parsed = parseMemoryFrontmatter(entry.content)
+    if (!parsed) {
+      result.skipped++
+      continue
+    }
+
+    try {
+      const existing = findSimilarPersonalMemory(db, userId, parsed.name)
+      if (existing) {
+        const updated = updateMemory(existing.id, {
+          content: parsed.content,
+          description: parsed.description ?? undefined,
+        })
+        if (updated) result.updated++
+      } else {
+        createMemory({
+          scopeKind: 'personal',
+          ownerUserId: userId,
+          name: parsed.name,
+          description: parsed.description,
+          type: parsed.type,
+          content: parsed.content,
+          layer: 'semantic',
+          sourceSessionId: sessionId,
+        })
+        result.created++
+      }
+    } catch (err) {
+      if (err instanceof MemoryError) {
+        result.skipped++
+      } else {
+        throw err
+      }
+    }
+  }
+
+  if (result.created + result.updated > 0) {
+    try {
+      publishSessionEvent(
+        sessionId,
+        'memory_synced',
+        { created: result.created, updated: result.updated },
+        'outbound',
+      )
+    } catch (err) {
+      logError(`[memories] notify event failed session=${sessionId}:`, err)
+    }
+    log(
+      `[memories] sync session=${sessionId} created=${result.created} updated=${result.updated} skipped=${result.skipped}`,
+    )
+  }
+  return result
+}
+
+interface ParsedMemoryFile {
+  name: string
+  description?: string
+  type: MemoryType
+  content: string
+}
+
+const MEMORY_TYPE_SET = new Set<string>(MEMORY_TYPES)
+
+/** Minimal frontmatter parse (name/description/type) — memdir file shape. */
+function parseMemoryFrontmatter(raw: string): ParsedMemoryFile | null {
+  if (!raw.startsWith('---')) return null
+  const end = raw.indexOf('\n---', 3)
+  if (end < 0) return null
+  const header = raw.slice(3, end)
+  const body = raw.slice(end + 4).replace(/^\n+/, '')
+
+  const fields = new Map<string, string>()
+  for (const line of header.split('\n')) {
+    const idx = line.indexOf(':')
+    if (idx > 0) {
+      fields.set(line.slice(0, idx).trim(), line.slice(idx + 1).trim())
+    }
+  }
+
+  const name = fields.get('name')
+  const type = fields.get('type')
+  if (!name || !type || !MEMORY_TYPE_SET.has(type)) return null
+  if (!body.trim()) return null
+
+  return {
+    name,
+    description: fields.get('description') || undefined,
+    type: type as MemoryType,
+    content: body,
+  }
+}
+
+/** Dedup recall: exact-name match first, then FTS name match, owner-scoped. */
+function findSimilarPersonalMemory(
+  db: Database,
+  userId: string,
+  name: string,
+): MemoryRow | null {
+  const exact = db
+    .query(
+      `SELECT * FROM memories
+       WHERE scope_kind = 'personal' AND owner_user_id = $uid
+         AND status = 'active' AND name = $name
+       LIMIT 1`,
+    )
+    .get({ $uid: userId, $name: name }) as MemoryRow | null
+  if (exact) return exact
+
+  try {
+    const hit = db
+      .query(
+        `SELECT m.* FROM memories m
+         JOIN memories_fts f ON f.memory_id = m.id
+         WHERE memories_fts MATCH $query
+           AND m.scope_kind = 'personal' AND m.owner_user_id = $uid
+           AND m.status = 'active'
+         LIMIT 1`,
+      )
+      .get({
+        $query: `"${name.replace(/"/g, '""')}"`,
+        $uid: userId,
+      }) as MemoryRow | null
+    return hit ?? null
+  } catch (err) {
+    logError('[memories] dedup fts lookup failed:', err)
+    return null
+  }
+}