@aiwuk/team 0.0.0-stage → 5.0.3

package/memory-hub.js

@@ -0,0 +1,150 @@
+import { m as modelText } from './i18n.js';
+// Memory hub: what the team learned (handoffs, accepted results, pitfalls, decisions) is kept per project,
+// recalled into each member's runtime context when it receives work, and searchable on demand. Ingestion is
+// automatic for handoffs and teammates' final reports; members can also write a memory explicitly.
+// Recall is capped (MEMORY_LIMITS.injectChars) and only changes when the task changes, so it costs little
+// context and does not resend the runtime snapshot every step.
+import { createEmbedder } from './memory-embed.js';
+import { createMemoryBackend } from './memory-backends.js';
+import { redactSecrets } from './memory-redact.js';
+import { MEMORY_KINDS, MEMORY_LIMITS, createMemoryStore } from './memory-store.js';
+import { baseName } from './session-rotation.js';
+import { params } from './tool-schema.js';
+import { ownsCapabilityTeam } from './preset-guard.js';
+const output = { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] };
+const SCOPES = ['project', 'role', 'session', 'global'];
+const messageText = message => (Array.isArray(message?.content) ? message.content.map(c => c?.text ?? '').join('\n') : String(message?.text ?? message?.content ?? '')).trim();
+export function createMemoryHub(ctx, team, { store = createMemoryStore(team.root), embedder = createEmbedder(), backend = createMemoryBackend({ label: modelText('memory-hub.280') }), secrets = () => [] } = {}) {
+  const recall = new Map(); // agent id → { query, block }
+  const reports = new Map(); // `${session}:${callId}` → text of a pending teammate report
+  const identity = agent => {
+    const m = ctx.agentTeams.tryMembership(agent);
+    if (!m || !ownsCapabilityTeam(ctx, agent)) return undefined;
+    return { project: team.pinned(agent) ?? team.pinned(m.root ?? agent), role: m.role === 'lead' ? 'lead' : baseName(m.name), session: agent.id, lead: m.role === 'lead', leadId: (m.root ?? agent).id, name: m.name ?? 'lead' };
+  };
+  const embedOne = async (text, purpose) => { const out = await embedder.embed([text], purpose); return out ? { vector: out.vectors[0], model: out.model } : null; };
+  async function backfill(project) {
+    if (!embedder.available) return;
+    const missing = await store.unembedded(project, 16, embedder.vectorKey);
+    if (!missing.length) return;
+    const out = await embedder.embed(missing.map(m => m.text), 'passage');
+    if (out) for (let i = 0; i < missing.length; i++) await store.setVector(missing[i], out.vectors[i], out.model);
+  }
+  const hub = {
+    async write(who, { kind, text, scope = 'role', tags, key }) {
+      if (!who?.project) throw new Error(modelText('memory-hub.281'));
+      if (!SCOPES.includes(scope)) throw new Error(modelText('memory-hub.282', { 0: SCOPES.join(' / ') }));
+      if (scope === 'global' && !who.lead) throw new Error(modelText('memory-hub.283'));
+      // Secrets never enter memory: it is recalled into other members' prompts and may leave this machine.
+      const clean = redactSecrets(String(text ?? ''), await Promise.resolve(secrets()).catch(() => []));
+      const embedded = await embedOne(clean, 'passage');
+      const s = scope === 'global' ? { kind: 'global' } : scope === 'project' ? { kind: 'project', project: who.project }
+        : scope === 'session' ? { kind: 'session', project: who.project, session: who.session } : { kind: 'role', project: who.project, role: who.role };
+      const saved = await store.write({ scope: s, kind, text: clean, tags: Array.isArray(tags) ? tags.map(String).slice(0, 10) : [], key: key ? String(key).slice(0, 120) : null,
+        vector: embedded?.vector ?? null, model: embedded?.model ?? null, source: { member: who.name, session: who.session, lead: who.leadId, at: Date.now() } });
+      // Session-scoped notes stay local; everything else also becomes shared long-term memory.
+      if (scope !== 'session') {
+        try {
+          if (saved.superseded?.length) backend.revoke?.(saved.superseded);
+          if (!saved.merged || saved.superseded?.length) backend.enqueue(saved.memory, who);
+        } catch (error) { saved.syncError = error.message; }
+      }
+      return saved;
+    },
+    async search(who, { query, k = 6, kinds }) {
+      // The query goes to the embedding service and the shared backend, so it is filtered like a stored memory.
+      const q = redactSecrets(String(query ?? '').slice(0, 4000), await Promise.resolve(secrets()).catch(() => [])).slice(0, 2000);
+      const limit = Math.min(Math.max(1, k), 20);
+      const [embedded, shared] = await Promise.all([q ? embedOne(q, 'query') : null, kinds ? [] : backend.recall(q)]);
+      void backfill(who.project).catch(() => {});
+      const local = await store.search({ project: who.project, role: who.lead ? undefined : who.role, session: who.session, query: q, vector: embedded?.vector, vectorModel: embedded?.model, k: limit, kinds });
+      // Team memories first (scoped to this project/role), then shared long-term ones not already covered.
+      const seen = new Set(local.map(r => r.memory.text));
+      const results = []; let chars = 0;
+      for (const row of [...local, ...shared.filter(r => !seen.has(r.memory.text))]) {
+        const size = JSON.stringify(row.memory.text).length;
+        if (results.length >= limit || chars + size > 12000) continue;
+        results.push(row); chars += size;
+      }
+      return { results, mode: embedded ? 'hybrid' : 'text', embedError: embedded ? null : embedder.lastError, ...(backend.enabled ? { shared: { backend: backend.name, count: shared.length, error: backend.lastError } } : {}) };
+    },
+    backend,
+    /** Called by rotation after a member writes its handoff. */
+    async ingestHandoff(h) {
+      const who = { project: team.pinned(ctx.agents.get(h.session)) ?? undefined, role: h.role, session: h.session, lead: false, leadId: h.lead, name: h.member };
+      if (!who.project) return;
+      const w = h.written ?? {};
+      if (w.done || w.remaining) await hub.write(who, { kind: 'handoff', scope: 'role', key: `handoff:${h.role}`, text: modelText('memory-hub.284', { 0: h.member, 1: w.done || '—', 2: w.remaining || '—', 3: w.verify ? modelText('memory-hub.285', { 0: w.verify }) : '' }) });
+      if (w.pitfalls) await hub.write(who, { kind: 'pitfall', scope: 'project', text: modelText('memory-hub.286', { 0: h.role, 1: w.pitfalls }) });
+    },
+    /** Memory block for a member's runtime context; refreshed when its task text changes. */
+    async refreshRecall(agent, query) {
+      const who = identity(agent);
+      if (!who?.project || !query) return;
+      const prior = recall.get(agent.id);
+      if (prior?.query === query) return;
+      const { results } = await hub.search(who, { query, k: 8 });
+      const block = store.format(results, MEMORY_LIMITS.injectChars);
+      recall.set(agent.id, { query, block, ids: results.map(r => r.memory.id) });
+      const local = results.filter(r => SCOPES.includes(r.memory.scope.kind)); // backend hits are not in the store
+      if (local.length) await store.markUsed(local.map(r => r.memory));
+    },
+    recallText(agent) {
+      const r = recall.get(agent.id);
+      return r?.block ? modelText('memory-hub.287', { 0: r.block }) : '';
+    },
+    register() {
+      ctx.on('agent/created', ({ agent }) => {
+        if (!ownsCapabilityTeam(ctx, agent) || !ctx.agentTeams.tryMembership(agent)) return;
+        agent.ctx.systemPrompt.context({ name: 'capability-team:memory', order: 97, text: () => hub.recallText(agent) });
+      });
+      ctx.on('agent/inbox/claimed', ({ agent, message }) => {
+        const text = messageText(message);
+        if (text.length >= 8 && ownsCapabilityTeam(ctx, agent) && ctx.agentTeams.tryMembership(agent)) void hub.refreshRecall(agent, text.slice(0, 2000)).catch(() => {});
+      });
+      // A teammate's successful final report to the Lead becomes a 'result' memory of its role.
+      try {
+        ctx.on('session/event', (session, event) => {
+          const agent = session?.id && ctx.agents.get(session.id);
+          if (!ownsCapabilityTeam(ctx, agent) || ctx.agentTeams.tryMembership(agent)?.role !== 'teammate') return;
+          const d = event?.data ?? {};
+          if (event.type === 'tool/call' && d.name === 'send_message') {
+            let args = {}; try { args = typeof d.arguments === 'string' ? JSON.parse(d.arguments) : d.arguments ?? {}; } catch { return; }
+            if (args.target === 'lead' && String(args.message ?? '').length >= 200) reports.set(`${session.id}:${d.callId}`, String(args.message));
+          } else if (event.type === 'tool/result') {
+            const key = `${session.id}:${d.message?.toolCallId}`;
+            const text = reports.get(key);
+            if (text === undefined) return;
+            reports.delete(key);
+            if (!d.message?.isError) void hub.write(identity(agent), { kind: 'result', scope: 'role', text }).catch(() => {});
+          }
+        });
+      } catch { /* host without session observers: explicit writes still work */ }
+      ctx.effect(() => ctx.tools.register({ name: 'capability_memory_search', output,
+        description: modelText('memory-hub.288'),
+        parameters: params({ query: { type: 'string', description: modelText('memory-hub.289') }, k: { type: 'integer', description: modelText('memory-hub.290') },
+          kinds: { type: 'array', items: { type: 'string', enum: MEMORY_KINDS }, description: modelText('memory-hub.291') } }, ['query']),
+        async execute(args, exec) {
+          const who = identity(exec.agent);
+          if (!who) throw new Error(modelText('memory-hub.292'));
+          const { results, mode, embedError, shared } = await hub.search(who, args);
+          return JSON.stringify({ mode, ...(embedError ? { note: modelText('memory-hub.293', { 0: embedError }) } : {}),
+            ...(shared ? { shared: shared.error ? modelText('memory-hub.294', { 0: shared.backend, 1: shared.error }) : modelText('memory-hub.295', { 0: shared.count, 1: shared.backend }) } : {}),
+            results: results.map(r => ({ id: r.memory.id, kind: r.memory.kind, scope: r.memory.scope.kind, text: r.memory.text, via: r.via, updatedAt: r.memory.updatedAt })) });
+        },
+      }));
+      ctx.effect(() => ctx.tools.register({ name: 'capability_memory_write', output,
+        description: modelText('memory-hub.296'),
+        parameters: params({ kind: { type: 'string', enum: ['pitfall', 'decision', 'note'] }, text: { type: 'string' }, scope: { type: 'string', enum: SCOPES },
+          key: { type: 'string', description: modelText('memory-hub.297') }, tags: { type: 'array', items: { type: 'string' } } }, ['kind', 'text']),
+        async execute(args, exec) {
+          const { memory, merged, syncError } = await hub.write(identity(exec.agent), args);
+          return JSON.stringify({ saved: true, merged, ...(syncError ? { syncWarning: syncError } : {}), id: memory.id, kind: memory.kind, scope: memory.scope.kind, embedded: !!memory.vector });
+        },
+      }));
+      // Plugin reload or shutdown: send what is still queued for the shared long-term memory.
+      ctx.effect(() => () => { void backend.flush().catch(() => {}); });
+    },
+  };
+  return hub;
+}

package/memory-openviking.js

@@ -0,0 +1,101 @@
+import { m as modelText } from './i18n.js';
+// OpenViking backend for the memory hub (integrations.memory.backend = 'openviking').
+// The team's own store stays the source for role/session-scoped recall; every memory is also sent to the
+// OpenViking server, which extracts and indexes it as long-term memory shared by every agent and session that
+// uses that server (DSH, Codex, OpenClaw...). Recall merges OpenViking's context search into team results.
+// The server is optional at run time: when it is down, writes stay queued for the next flush and recall falls
+// back to the local store, so a stopped server never blocks a member.
+import { keyOf, refreshCredentials, resolveIntegrations } from './integrations-config.js';
+import { createSyncQueue } from './memory-sync-queue.js';
+import { defaultRoot } from './theme.js';
+import { join } from 'node:path';
+export const OV_SESSION_PREFIX = 'capability-team';
+const FLUSH_MS = 20000;
+const MAX_QUEUE = 200;
+const MAX_BATCH = 40;
+export function memorySettings(resolved = resolveIntegrations()) {
+  return { config: resolved.effective.memory, key: keyOf('memory', resolved) };
+}
+// `label` names the caller (e.g. 'Capability Team' for the team plugin, 'Global Memory' for global-memory) at the start of
+// every message sent upstream; the default is neutral (no caller name).
+export function createOpenViking({ settings, queuePath, label = '', warn = () => {}, fetcher = fetch, now = Date.now, schedule = (fn, ms) => { const t = setTimeout(fn, ms); t.unref?.(); return t; } } = {}) {
+  const current = () => settings ?? memorySettings();
+  const prefix = String(label ?? '').replace(/[【】\r\n]/g, '').trim().slice(0, 40);
+  const queue = createSyncQueue(queuePath ?? (settings ? null : join(defaultRoot(), 'memory', 'openviking-queue.json')), { max: MAX_QUEUE, warn });
+  let timer = null;
+  let flushing = null;
+  const api = {
+    name: 'openviking',
+    lastError: null,
+    get enabled() { const { config } = current(); return config.backend === 'openviking' && !!config.url; },
+    async request(method, path, body, timeoutMs) {
+      if (!settings) await refreshCredentials().catch(() => {});
+      const { config, key } = current();
+      const headers = { 'Content-Type': 'application/json', ...(key ? { 'X-API-Key': key } : {}),
+        ...(config.account ? { 'X-OpenViking-Account': config.account } : {}), ...(config.user ? { 'X-OpenViking-User': config.user } : {}) };
+      const response = await fetcher(`${config.url}/api/v1${path}`, { method, headers, redirect: 'error',
+        body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(timeoutMs ?? config.timeoutMs) });
+      const text = await response.text();
+      if (!response.ok) throw new Error(`OpenViking HTTP ${response.status}${response.status === 401 || response.status === 403 ? modelText('memory-openviking.298') : ''}`);
+      let data; try { data = JSON.parse(text); } catch { throw new Error(modelText('memory-openviking.299')); }
+      if (data?.status && data.status !== 'ok') throw new Error(modelText('memory-openviking.300', { 0: String(data.status).slice(0, 40) }));
+      return data?.result ?? data;
+    },
+    /** Queue one memory for the next commit; the text is already redacted by the hub. */
+    enqueue(memory, who) {
+      if (!api.enabled) return false;
+      // Only the project's folder name goes upstream: the full path exposes this machine's layout and user name.
+      const projectName = String(who?.project ?? '').split(/[\\/]/).filter(Boolean).pop();
+      const where = [projectName ? modelText('memory-openviking.301', { 0: projectName }) : null, memory.scope?.kind === 'role' ? modelText('memory-openviking.302', { 0: memory.scope.role }) : null].filter(Boolean).join(' · ');
+      queue.push({ role: 'user', content: `【${prefix}${memory.kind === 'pitfall' ? modelText('memory-openviking.303') : memory.kind === 'decision' ? modelText('memory-openviking.304') : modelText('memory-openviking.305')}${where ? ` · ${where}` : ''}】${memory.text}` });
+      api.lastError = null;
+      if (!timer) timer = schedule(() => { timer = null; void api.flush().catch(() => {}); }, FLUSH_MS);
+      return true;
+    },
+    /** Send queued memories as one session and commit it for extraction; failures keep them queued. */
+    async flush() {
+      if (flushing) return flushing;
+      if (!queue.size() || !api.enabled) return { sent: 0 };
+      flushing = (async () => {
+        const batch = queue.peek(MAX_BATCH);
+        const sid = `${OV_SESSION_PREFIX}-${now()}`;
+        try {
+          await api.request('POST', '/sessions', { session_id: sid });
+          for (const { role, content } of batch) await api.request('POST', `/sessions/${sid}/messages`, { role, content });
+          await api.request('POST', `/sessions/${sid}/commit`, {});
+          queue.ack(batch);
+          api.lastError = null;
+          return { sent: batch.length, session: sid };
+        } catch (error) { api.lastError = error.message; throw error; }
+        finally { flushing = null; if (queue.size() && !timer) timer = schedule(() => { timer = null; void api.flush().catch(() => {}); }, FLUSH_MS); }
+      })();
+      return flushing;
+    },
+    /** Long-term memories relevant to `query`, as hub results; [] when disabled or unreachable. */
+    async recall(query, limit) {
+      if (!api.enabled || !query) return [];
+      const { config } = current();
+      try {
+        const result = await api.request('POST', '/search/search', { query: String(query).slice(0, 2000), mode: 'context', limit: limit ?? config.recallLimit });
+        api.lastError = null;
+        return (Array.isArray(result?.entries) ? result.entries : []).filter(e => typeof e?.text === 'string' && e.text.trim() && !queue.revoked().some(t => e.text.includes(t))).slice(0, limit ?? config.recallLimit)
+          .map(e => ({ score: Number(e.score) || 0, via: ['openviking'], memory: { id: e.uri, kind: 'note', scope: { kind: 'openviking', category: e.category }, text: e.text.trim().slice(0, 1200), uri: e.uri } }));
+      } catch (error) { api.lastError = error.message; return []; }
+    },
+    async status() {
+      if (!api.enabled) return { enabled: false };
+      const { config } = current();
+      const response = await fetcher(`${config.url}/health`, { signal: AbortSignal.timeout(5000), redirect: 'error' });
+      return { enabled: true, healthy: response.ok, queued: queue.size(), lastError: api.lastError, ...(response.ok ? await response.json() : {}) };
+    },
+    revoke(memories) {
+      const texts = memories.map(m => m.text).filter(Boolean);
+      queue.revoke(texts);
+      for (const text of texts) queue.push({ role: 'user', content: modelText('memory-openviking.306', { 0: text }) });
+      if (!timer) timer = schedule(() => { timer = null; void api.flush().catch(() => {}); }, FLUSH_MS);
+    },
+    pending: () => queue.size(),
+  };
+  if (queue.size()) timer = schedule(() => { timer = null; void api.flush().catch(() => {}); }, FLUSH_MS);
+  return api;
+}

package/memory-redact.js

@@ -0,0 +1,34 @@
+import { m as modelText } from './i18n.js';
+// Secret filter applied to every memory before it is stored locally or sent to an external memory service.
+// Memories are recalled into other members' prompts later, so a leaked token would spread; values are
+// replaced with a marker instead of rejecting the whole memory, which usually still carries the useful lesson.
+const PATTERNS = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)/g,
+  /\b(?:sk|pk|rk)-(?:[A-Za-z0-9_-]{2,16}-)?[A-Za-z0-9_-]{16,}\b/g,
+  /\b(?:ghp|gho|ghu|ghs|ghr|github_pat)_[A-Za-z0-9_]{20,}\b/g,
+  /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g,
+  /\bAKIA[0-9A-Z]{16}\b/g,
+  /\b(?:tvly|xai|gsk|glpat)-[A-Za-z0-9_-]{16,}\b/g,
+  /\b(?:jina|hf|npm)_[A-Za-z0-9_]{16,}\b/g,
+  /\bBSA[A-Za-z0-9_-]{20,}\b/g,
+  /\bAIza[0-9A-Za-z_-]{35}\b/g,
+  /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g,
+  /\b(Bearer|Basic)\s+[A-Za-z0-9._~+\/=-]{16,}/gi,
+  /\b([a-z][a-z0-9+.-]*:\/\/)[^\s:@\/]+:[^\s@\/]+@/gi,
+  // Any name ending in one of these, so OPENVIKING_API_KEY=… and GH_TOKEN=… match as well as key=…
+  /\b((?:[\w-]*(?:key|token|secret|password|passwd|pwd)|auth)["']?\s*[:=]\s*["']?)[^\s"',;]{8,}/gi,
+];
+export const REDACTED = modelText('memory-redact.307');
+/** Text with likely secrets replaced; `extra` are exact values (e.g. keys from the credential store). */
+export function redactSecrets(text, extra = []) {
+  let out = String(text ?? '');
+  for (const value of extra) if (typeof value === 'string' && value.length >= 8) out = out.split(value).join(REDACTED);
+  for (const re of PATTERNS) {
+    out = out.replace(re, (match, prefix) => {
+      if (/^(bearer|basic)$/i.test(prefix ?? '')) return `${prefix} ${REDACTED}`;
+      if (typeof prefix === 'string' && /[:=@]|:\/\/$/.test(prefix)) return prefix.endsWith('://') ? `${prefix}${REDACTED}@` : `${prefix}${REDACTED}`;
+      return REDACTED;
+    });
+  }
+  return out;
+}

package/memory-store.js

@@ -0,0 +1,219 @@
+import { m as modelText } from './i18n.js';
+// Memory store: one JSONL file per project plus a global file, a BM25 full-text index built in memory
+// (Latin words + CJK character bigrams), optional vectors, and hybrid ranking by reciprocal rank fusion.
+// Writes merge near-duplicates instead of piling them up; ranking decays with age and rises with use.
+import { createHash, randomUUID } from 'node:crypto';
+import { appendFile, mkdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { cosine } from './memory-embed.js';
+import { acquireLock } from './theme.js';
+/** Several DSH processes (Desktop, `dsh web`, profiles) share the files: writes and compaction take a file lock. */
+async function withFileLock(path, fn) {
+  let handle = null;
+  for (let attempt = 0; !handle; attempt++) {
+    try { handle = await acquireLock(`${path}.lock`); }
+    catch (error) { if (attempt >= 100 || ['EACCES', 'EPERM', 'ENOENT'].includes(error.code) && attempt >= 3) throw error; await new Promise(r => setTimeout(r, 30)); }
+  }
+  try { return await fn(); } finally { await handle.close().catch(() => {}); await unlink(`${path}.lock`).catch(() => {}); }
+}
+export const MEMORY_KINDS = ['handoff', 'result', 'pitfall', 'decision', 'note'];
+export const MEMORY_LIMITS = { maxText: 2000, maxPerFile: 2000, halfLifeDays: 30, pruneDays: 180, duplicateCosine: 0.92, injectChars: 2400 };
+const DAY = 86400000;
+/** Tokens for BM25: lowercase Latin/digit words and CJK unigrams + bigrams. */
+/** Superseded JSONL lines tolerated beyond twice the live count before a file is rewritten. */
+const COMPACT_SLACK = 200;
+export function tokenize(text) {
+  const out = [];
+  const s = String(text ?? '').toLowerCase();
+  for (const w of s.match(/[a-z0-9_][a-z0-9_.-]*/g) ?? []) out.push(w);
+  const cjk = s.match(/[\u3400-\u9fff\uf900-\ufaff]+/g) ?? [];
+  for (const run of cjk) { for (let i = 0; i < run.length; i++) { out.push(run[i]); if (i + 1 < run.length) out.push(run.slice(i, i + 2)); } }
+  return out;
+}
+const normText = text => String(text ?? '').replace(/\s+/g, ' ').trim();
+const fileKey = project => (project ? createHash('sha256').update(project).digest('hex').slice(0, 32) : 'global');
+/** Whether a memory is visible to a reader: its project, and role/session scopes when narrower. */
+export function visible(m, { project, role, session }) {
+  if (m.supersededBy) return false;
+  if (m.scope.kind === 'global') return true;
+  if (m.scope.project !== project) return false;
+  if (m.scope.kind === 'role') return !role || m.scope.role === role;
+  if (m.scope.kind === 'session') return m.scope.session === session;
+  return true;
+}
+function bm25(docs, query) {
+  const q = [...new Set(tokenize(query))];
+  if (!q.length || !docs.length) return new Map();
+  const tf = docs.map(d => { const m = new Map(); for (const t of tokenize(d.text)) m.set(t, (m.get(t) ?? 0) + 1); return m; });
+  const lengths = tf.map(m => [...m.values()].reduce((a, b) => a + b, 0));
+  const avg = lengths.reduce((a, b) => a + b, 0) / docs.length || 1;
+  const scores = new Map();
+  for (const term of q) {
+    const df = tf.filter(m => m.has(term)).length;
+    if (!df) continue;
+    const idf = Math.log(1 + (docs.length - df + 0.5) / (df + 0.5));
+    tf.forEach((m, i) => {
+      const f = m.get(term); if (!f) return;
+      scores.set(docs[i].id, (scores.get(docs[i].id) ?? 0) + idf * (f * 2.2) / (f + 1.2 * (0.25 + 0.75 * lengths[i] / avg)));
+    });
+  }
+  return scores;
+}
+/** Hybrid rank: RRF over BM25 and cosine, times recency decay and a small boost for memories that helped before. */
+export function rank(docs, query, queryVector, { now = Date.now(), halfLifeDays = MEMORY_LIMITS.halfLifeDays, vectorModel } = {}) {
+  const text = bm25(docs, query);
+  const byText = [...text.entries()].sort((a, b) => b[1] - a[1]).map(([id]) => id);
+  // Vectors from another model or dimension count are not comparable, even when the lengths match.
+  const byVec = queryVector ? docs.filter(d => !vectorModel || d.model === vectorModel).map(d => [d.id, cosine(d.vector, queryVector)]).filter(([, s]) => s !== undefined && s > 0.2).sort((a, b) => b[1] - a[1]).map(([id]) => id) : [];
+  const fused = new Map();
+  byText.forEach((id, i) => fused.set(id, (fused.get(id) ?? 0) + 1 / (60 + i)));
+  byVec.forEach((id, i) => fused.set(id, (fused.get(id) ?? 0) + 1 / (60 + i)));
+  return docs.filter(d => fused.has(d.id)).map(d => {
+    const age = Math.max(0, now - (d.updatedAt ?? d.createdAt)) / DAY;
+    const decay = Math.pow(0.5, age / halfLifeDays);
+    return { memory: d, score: fused.get(d.id) * (0.3 + 0.7 * decay) * (1 + Math.min(d.hits ?? 0, 10) * 0.05), via: [text.has(d.id) ? 'text' : null, byVec.includes(d.id) ? 'vector' : null].filter(Boolean) };
+  }).sort((a, b) => b.score - a.score);
+}
+export function createMemoryStore(root, { now = Date.now, limits = MEMORY_LIMITS } = {}) {
+  const dir = join(root, 'memory');
+  const cache = new Map(); // file key → memories
+  const seen = new Map(); // file key → size:mtime of the file as last read or written by this process
+  const lines = new Map(); // file key → JSONL lines in the file (live records plus superseded appends)
+  const pathOf = key => join(dir, `${key}.jsonl`);
+  const stamp = async key => { try { const s = await stat(pathOf(key)); return `${s.size}:${s.mtimeMs}`; } catch { return 'none'; } };
+  async function load(key) {
+    // Another process may have appended or compacted since: re-read when the file changed under us.
+    // Stamped before reading, so an append that lands during the read makes the next load read again.
+    const current = await stamp(key);
+    if (cache.has(key) && seen.get(key) === current) return cache.get(key);
+    let list = [];
+    try {
+      const latest = new Map();
+      let count = 0;
+      for (const line of (await readFile(pathOf(key), 'utf8')).split('\n')) {
+        if (!line.trim()) continue;
+        count++;
+        try { const m = JSON.parse(line); latest.set(m.id, m); } catch { /* a torn last line is skipped */ }
+      }
+      list = [...latest.values()].filter(m => !m.deleted);
+      lines.set(key, count);
+    } catch (error) { if (error.code !== 'ENOENT') throw error; lines.set(key, 0); }
+    const previous = cache.get(key);
+    if (previous) { previous.length = 0; previous.push(...list); list = previous; } // keep callers' array identity
+    cache.set(key, list);
+    seen.set(key, current);
+    return list;
+  }
+  async function persist(key, record) {
+    await mkdir(dir, { recursive: true });
+    await withFileLock(pathOf(key), async () => {
+      const before = await stamp(key);
+      await appendFile(pathOf(key), JSON.stringify(record) + '\n');
+      lines.set(key, (lines.get(key) ?? 0) + 1);
+      // Only our own append happened since the last read: the cache is still current.
+      if (seen.get(key) === before) seen.set(key, await stamp(key));
+    });
+    // Every update (hits on recall, merges, vectors) appends the whole record again; without this the file grows
+    // without bound even though the live set is capped. Rewrite once superseded lines outnumber live ones.
+    if ((lines.get(key) ?? 0) > 2 * (cache.get(key)?.length ?? 0) + COMPACT_SLACK) await compact(key);
+  }
+  /** Rewrite the file from its current content (re-read under the lock, so other processes' appends survive). */
+  async function compact(key, select = list => list) {
+    await mkdir(dir, { recursive: true });
+    return withFileLock(pathOf(key), async () => {
+      seen.delete(key);
+      const list = await load(key);
+      const keep = [...select(list)]; // a copy: `list` is cleared and refilled below
+      const temp = `${pathOf(key)}.${randomUUID()}.tmp`;
+      await writeFile(temp, keep.map(m => JSON.stringify(m)).join('\n') + (keep.length ? '\n' : ''));
+      await rename(temp, pathOf(key));
+      lines.set(key, keep.length);
+      list.length = 0; list.push(...keep);
+      seen.set(key, await stamp(key));
+      return keep;
+    });
+  }
+  const keyOf = scope => (scope.kind === 'global' ? 'global' : fileKey(scope.project));
+  // One operation at a time per store: a write adds its record to the cached list before appending it, so a reload
+  // in between would drop the record from the cache while the append then marks that cache as current. The record
+  // would stay on disk but be invisible to every search until the file next changed.
+  let tail = Promise.resolve();
+  const serial = fn => { const run = tail.then(fn); tail = run.catch(() => {}); return run; };
+  const raw = {
+    /** Insert, or merge into a near-duplicate in the same scope (same normalized text, or cosine ≥ threshold). */
+    async write({ scope, kind, text, tags = [], source = {}, vector = null, model = null, key: topic = null }) {
+      if (!MEMORY_KINDS.includes(kind)) throw new Error(modelText('memory-store.308', { 0: MEMORY_KINDS.join(' / ') }));
+      const body = normText(text).slice(0, limits.maxText);
+      if (body.length < 4) throw new Error(modelText('memory-store.309'));
+      if (scope.kind !== 'global' && !scope.project) throw new Error(modelText('memory-store.310'));
+      const fk = keyOf(scope);
+      const list = await load(fk);
+      const same = m => m.kind === kind && JSON.stringify(m.scope) === JSON.stringify(scope) && !m.supersededBy;
+      const at = now();
+      const superseded = [];
+      // A memory with the same topic key replaces the older ones (conflict update: newest wins).
+      const supersede = async keeper => {
+        if (!topic) return;
+        for (const old of list.filter(m => same(m) && m.key === topic && m.id !== keeper.id)) { superseded.push({ ...old }); old.supersededBy = keeper.id; old.updatedAt = at; await persist(fk, old); }
+      };
+      const dup = list.find(m => same(m) && (normText(m.text) === body || (vector && m.model === model && cosine(m.vector, vector) >= limits.duplicateCosine)));
+      if (dup) {
+        Object.assign(dup, { text: body.length >= dup.text.length ? body : dup.text, tags: [...new Set([...dup.tags, ...tags])], updatedAt: at, merged: (dup.merged ?? 0) + 1, ...(topic ? { key: topic } : {}), ...(vector ? { vector, model } : {}) });
+        await persist(fk, dup);
+        await supersede(dup);
+        return { memory: dup, merged: true, superseded };
+      }
+      const memory = { id: randomUUID(), scope, kind, text: body, tags: [...new Set(tags)], source, key: topic, vector, model, createdAt: at, updatedAt: at, hits: 0 };
+      list.push(memory);
+      await persist(fk, memory);
+      await supersede(memory);
+      if (list.length > limits.maxPerFile) await this.prune(scope);
+      return { memory, merged: false, superseded };
+    },
+    /** Visible memories for a reader, ranked for `query`. */
+    async search({ project, role, session, query, vector, vectorModel, k = 6, kinds }) {
+      const pool = [...await load('global'), ...(project ? await load(fileKey(project)) : [])]
+        .filter(m => visible(m, { project, role, session }) && (!kinds || kinds.includes(m.kind)));
+      return rank(pool, query, vector, { now: now(), halfLifeDays: limits.halfLifeDays, vectorModel }).slice(0, k);
+    },
+    async markUsed(memories) {
+      const at = now();
+      for (const m of memories) { m.hits = (m.hits ?? 0) + 1; m.lastUsedAt = at; await persist(keyOf(m.scope), m); }
+    },
+    /** Memories without a vector of the current model (for backfill once embeddings work or after a model change). */
+    async unembedded(project, limit = 64, vectorModel = null) {
+      return [...await load('global'), ...(project ? await load(fileKey(project)) : [])].filter(m => !m.supersededBy && (!m.vector || (vectorModel && m.model !== vectorModel))).slice(0, limit);
+    },
+    async setVector(m, vector, model) { m.vector = vector; m.model = model; await persist(keyOf(m.scope), m); },
+    /** Forget: drop superseded entries and unused old ones, keep the newest maxPerFile. */
+    async prune(scope) {
+      const cutoff = now() - limits.pruneDays * DAY;
+      let removed = 0;
+      await compact(keyOf(scope), list => {
+        const keep = list.filter(m => !m.supersededBy && !((m.hits ?? 0) === 0 && (m.updatedAt ?? m.createdAt) < cutoff))
+          .sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0)).slice(0, limits.maxPerFile);
+        removed = list.length - keep.length;
+        return keep;
+      });
+      return removed;
+    },
+    async remove(scope, id) {
+      const fk = keyOf(scope); const list = await load(fk);
+      const i = list.findIndex(m => m.id === id); if (i < 0) return false;
+      const [m] = list.splice(i, 1); await persist(fk, { ...m, deleted: true }); return true;
+    },
+    /** Text block for automatic injection: newest-first ranked memories within a character budget. */
+    format(results, maxChars = limits.injectChars) {
+      const lines = []; let used = 0;
+      for (const { memory: m } of results) {
+        const line = `- [${m.kind}${m.scope.kind === 'role' ? `·${m.scope.role}` : ''}] ${m.text}`;
+        if (used + line.length + (lines.length ? 1 : 0) > maxChars) continue;
+        used += line.length + (lines.length ? 1 : 0); lines.push(line);
+      }
+      return lines.join('\n');
+    },
+  };
+  const store = { ...raw };
+  for (const name of ['write', 'search', 'markUsed', 'unembedded', 'setVector', 'prune', 'remove']) store[name] = (...args) => serial(() => raw[name](...args));
+  return store;
+}

package/memory-sync-queue.js

@@ -0,0 +1,28 @@
+import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+// Atomic disk snapshots; overflow is explicit and never silently drops older messages.
+export function createSyncQueue(path, { max = 200, warn = () => {} } = {}) {
+  let rows = [], revoked = [];
+  if (path) {
+    try { const saved = JSON.parse(readFileSync(path, 'utf8')); rows = saved.rows ?? []; revoked = saved.revoked ?? []; }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  const persist = () => {
+    if (!path) return;
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = `${path}.${randomUUID()}.tmp`;
+    writeFileSync(temp, JSON.stringify({ rows, revoked }), { mode: 0o600 }); renameSync(temp, path);
+  };
+  return {
+    push(row) {
+      if (rows.length >= max) { warn('OpenViking sync queue full; memory retained locally'); throw new Error('OpenViking sync queue full'); }
+      rows.push({ ...row, queueId: randomUUID() }); persist();
+    },
+    peek: (n = 40) => rows.slice(0, n),
+    ack(batch) { const ids = new Set(batch.map(r => r.queueId)); rows = rows.filter(r => !ids.has(r.queueId)); persist(); },
+    revoke(texts) { revoked = [...new Set([...revoked, ...texts])]; persist(); },
+    revoked: () => [...revoked],
+    size: () => rows.length,
+  };
+}

package/model-policy.js

@@ -0,0 +1,85 @@
+import { m as modelText } from './i18n.js';
+// The (profile-wide) model policy is applied to a resolved role before the failover state chooses a route.
+// Entries are exact provider/model routes, or prefix rules ending in "*" that match either the full
+// route or the bare model id (so "@cf/*" covers every provider). No lower-tier substitution.
+export const routeKey = route => `${route.provider}/${route.model}`;
+export const isPrefixRule = entry => entry.endsWith('*');
+export function validateDisabledRoutes(value) {
+  if (!Array.isArray(value) || value.length > 2000) throw new Error(modelText('model-policy.311'));
+  for (const v of value) {
+    if (typeof v !== 'string' || !v.trim() || v.length > 512 || /[\r\n\0\s]/.test(v)) throw new Error(modelText('model-policy.312'));
+    if (isPrefixRule(v)) {
+      if (v.length < 3 || v.slice(0, -1).includes('*')) throw new Error(modelText('model-policy.313', { 0: v }));
+    } else if (!v.includes('/') || v.includes('*')) throw new Error(modelText('model-policy.314'));
+  }
+  return [...new Set(value)].sort();
+}
+/** Predicate over provider/model keys for a validated disabled list. */
+export function routeMatcher(disabledRoutes = []) {
+  const exact = new Set(), prefixes = [];
+  for (const entry of validateDisabledRoutes(disabledRoutes)) (isPrefixRule(entry) ? prefixes.push(entry.slice(0, -1)) : exact.add(entry));
+  return key => {
+    if (exact.has(key)) return true;
+    const model = key.slice(key.indexOf('/') + 1);
+    return prefixes.some(p => key.startsWith(p) || model.startsWith(p));
+  };
+}
+export function applyModelPolicy(role, disabledRoutes = []) {
+  const disabled = routeMatcher(disabledRoutes);
+  if (role.unassigned || !role.provider || !role.model) return role;
+  const candidates = [{ provider: role.provider, model: role.model }, ...(role.fallbacks ?? [])];
+  const allowed = candidates.filter(r => !disabled(routeKey(r)));
+  if (!allowed.length) throw new Error(modelText('model-policy.315', { 0: role.displayName ?? role.id }));
+  const [primary, ...fallbacks] = allowed;
+  // A disabled long-context route is dropped; requests then stay on the allowed primary and backups.
+  const { longContext, ...rest } = role;
+  const keep = longContext && !disabled(routeKey(longContext)) ? { longContext } : {};
+  return { ...rest, ...primary, fallbacks, ...keep, policyExcluded: candidates.filter(r => disabled(routeKey(r))).map(routeKey) };
+}
+/** Roles as requests see them under the policy: excluded routes dropped, roles with no allowed route marked blocked. */
+export function policyRoleView(roles, disabledRoutes = []) {
+  return roles.map(role => {
+    try { return applyModelPolicy(role, disabledRoutes); }
+    catch (error) { return { ...role, provider: undefined, model: undefined, fallbacks: [], blocked: error.message }; }
+  });
+}
+export function allocationPreview(roles, disabledRoutes) {
+  return roles.map(role => {
+    try {
+      const resolved = applyModelPolicy(role, disabledRoutes);
+      return { id: role.id, displayName: role.displayName ?? role.id,
+        status: resolved.provider && resolved.model ? 'eligible' : 'unassigned',
+        primary: resolved.provider && resolved.model ? routeKey(resolved) : null,
+        fallbacks: (resolved.fallbacks ?? []).map(routeKey) };
+    } catch (error) {
+      return { id: role.id, displayName: role.displayName ?? role.id, status: 'blocked', primary: null, fallbacks: [], reason: error.message };
+    }
+  });
+}
+export function modelPolicyRows(tiers, roles, disabledRoutes = [], catalog = []) {
+  const disabledList = validateDisabledRoutes(disabledRoutes);
+  const isDisabled = routeMatcher(disabledList);
+  const rows = new Map();
+  for (const entry of catalog) {
+    const slash = typeof entry === 'string' ? entry.indexOf('/') : -1;
+    const candidate = typeof entry === 'string'
+      ? { provider: entry.slice(0, slash), model: entry.slice(slash + 1) } : entry;
+    if (!candidate?.provider || !candidate.model || (typeof entry === 'string' && slash < 1)) continue;
+    const key = routeKey(candidate);
+    rows.set(key, { key, provider: candidate.provider, model: candidate.model,
+      tiers: candidate.tier ? [candidate.tier] : [], primaryFor: [], fallbackFor: [],
+      disabled: isDisabled(key), verified: false });
+  }
+  for (const role of roles) {
+    if (!role.provider || !role.model) continue;
+    for (const [index, route] of [{ provider: role.provider, model: role.model }, ...(role.fallbacks ?? [])].entries()) {
+      const key = routeKey(route);
+      const row = rows.get(key) ?? { key, provider: route.provider, model: route.model, tiers: [], primaryFor: [], fallbackFor: [], disabled: isDisabled(key), verified: false };
+      if (!row.tiers.includes(role.tier)) row.tiers.push(role.tier);
+      row[index === 0 ? 'primaryFor' : 'fallbackFor'].push(role.id);
+      rows.set(key, row);
+    }
+  }
+  // Catalog tier membership may contain unallocated IDs; don't invent a provider for them.
+  return { rows: [...rows.values()], tierCatalog: tiers, disabledRoutes: disabledList, allocations: allocationPreview(roles, disabledRoutes) };
+}