context-vault 3.9.0 → 3.10.0

package/src/remote.ts

@@ -45,6 +45,12 @@ export interface TeamSearchResult extends RemoteSearchResult {
   recall_members?: number;
 }
 
+export interface PublicSearchResult extends RemoteSearchResult {
+  source: 'public';
+  vault_slug: string;
+  recall_count: number;
+}
+
 export interface PrivacyScanMatch {
   type: string;
   value: string;
@@ -242,6 +248,103 @@ export class RemoteClient {
     }
   }
 
+  async publicSearch(slug: string, params: Record<string, unknown>): Promise<PublicSearchResult[]> {
+    try {
+      const query = new URLSearchParams();
+      if (params.query) query.set('q', String(params.query));
+      if (Array.isArray(params.tags) && params.tags.length) query.set('tags', params.tags.join(','));
+      if (params.kind) query.set('kind', String(params.kind));
+      if (params.category) query.set('category', String(params.category));
+      if (params.limit) query.set('limit', String(params.limit));
+      if (params.since) query.set('since', String(params.since));
+      if (params.until) query.set('until', String(params.until));
+
+      const res = await this.fetch(`/api/public/${slug}/search?${query.toString()}`);
+      if (!res.ok) return [];
+      const data = await res.json() as Record<string, unknown>;
+      const entries = Array.isArray(data.entries) ? data.entries : Array.isArray(data) ? data : [];
+      return (entries as PublicSearchResult[]).map(e => ({ ...e, source: 'public' as const, vault_slug: slug }));
+    } catch {
+      return [];
+    }
+  }
+
+  async publicRecall(slug: string, params: {
+    signal: string;
+    signal_type: string;
+    bucket?: string;
+    max_hints?: number;
+  }): Promise<RemoteHint[]> {
+    try {
+      const res = await this.fetch(`/api/public/${slug}/search`, {
+        method: 'POST',
+        body: JSON.stringify(params),
+      });
+      if (!res.ok) return [];
+      const data = await res.json() as Record<string, unknown>;
+      return Array.isArray(data.hints) ? data.hints : Array.isArray(data) ? data as RemoteHint[] : [];
+    } catch {
+      return [];
+    }
+  }
+
+  async publicList(params?: { domain?: string; sort?: string }): Promise<Record<string, unknown>[]> {
+    try {
+      const query = new URLSearchParams();
+      if (params?.domain) query.set('domain', params.domain);
+      if (params?.sort) query.set('sort', params.sort);
+
+      const res = await this.fetch(`/api/public/vaults?${query.toString()}`);
+      if (!res.ok) return [];
+      const data = await res.json() as Record<string, unknown>;
+      return Array.isArray(data.vaults) ? data.vaults as Record<string, unknown>[] : Array.isArray(data) ? data as Record<string, unknown>[] : [];
+    } catch {
+      return [];
+    }
+  }
+
+  async publicCreate(params: {
+    name: string;
+    slug: string;
+    description?: string;
+    domain_tags?: string[];
+    visibility?: string;
+  }): Promise<{ ok: boolean; slug?: string; error?: string }> {
+    try {
+      const res = await this.fetch('/api/public/vaults', {
+        method: 'POST',
+        body: JSON.stringify(params),
+      });
+      const data = await res.json().catch(() => ({})) as Record<string, unknown>;
+      if (res.ok) {
+        return { ok: true, slug: (data.slug as string) || params.slug };
+      }
+      return { ok: false, error: typeof data.error === 'string' ? data.error : `HTTP ${res.status}` };
+    } catch (e) {
+      return { ok: false, error: (e as Error).message };
+    }
+  }
+
+  async publicSeed(slug: string, entry: Record<string, unknown>): Promise<PublishResult> {
+    try {
+      const res = await this.fetch(`/api/public/${slug}/entries`, {
+        method: 'POST',
+        body: JSON.stringify(entry),
+      });
+      const data = await res.json().catch(() => ({})) as Record<string, unknown>;
+      if (res.ok) {
+        return { ok: true, id: data.id as string | undefined };
+      }
+      if (res.status === 422 && data.code === 'PRIVACY_SCAN_FAILED') {
+        const matches = Array.isArray(data.matches) ? data.matches as PrivacyScanMatch[] : [];
+        return { ok: false, error: 'Privacy scan failed', status: 422, privacyMatches: matches };
+      }
+      return { ok: false, error: typeof data.error === 'string' ? data.error : `HTTP ${res.status}`, status: res.status };
+    } catch (e) {
+      return { ok: false, error: (e as Error).message };
+    }
+  }
+
   private fetch(path: string, opts: RequestInit = {}): Promise<Response> {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
@@ -323,3 +426,45 @@ export function mergeWithTeamResults<T extends { id: string; score?: number; rec
   merged.sort((a, b) => ((b as any).score ?? 0) - ((a as any).score ?? 0));
   return merged.slice(0, limit);
 }
+
+/**
+ * Apply recall-driven ranking boost to public vault results.
+ * Uses freshness decay: entries not updated in 90+ days get 0.8 multiplier.
+ * Formula: score * log(1 + recall_count) * freshness_decay
+ */
+export function applyPublicRecallBoost<T extends { score?: number; recall_count?: number; updated_at?: string | null }>(
+  entries: T[]
+): T[] {
+  const now = Date.now();
+  const NINETY_DAYS_MS = 90 * 24 * 60 * 60 * 1000;
+  return entries.map(e => {
+    const baseScore = (e as any).score ?? 0;
+    const recallCount = (e as any).recall_count ?? 0;
+    if (recallCount === 0) return e;
+    const updatedAt = (e as any).updated_at ? new Date((e as any).updated_at).getTime() : now;
+    const freshnessDecay = (now - updatedAt > NINETY_DAYS_MS) ? 0.8 : 1.0;
+    const boostedScore = baseScore * Math.log(1 + recallCount) * freshnessDecay;
+    return { ...e, score: boostedScore };
+  });
+}
+
+/**
+ * Merge existing results with public vault results.
+ * Public results get recall-driven ranking boost with freshness decay before merge.
+ */
+export function mergeWithPublicResults<T extends { id: string; score?: number; recall_count?: number }>(
+  existing: T[],
+  publicResults: T[],
+  limit: number
+): T[] {
+  const existingIds = new Set(existing.map(r => r.id));
+  const uniquePublic = publicResults.filter(r => !existingIds.has(r.id));
+  const boostedPublic = applyPublicRecallBoost(uniquePublic);
+  const merged = [...existing, ...boostedPublic];
+  merged.sort((a, b) => ((b as any).score ?? 0) - ((a as any).score ?? 0));
+  return merged.slice(0, limit);
+}
+
+export function getPublicVaults(config: { remote?: RemoteConfig & { publicVaults?: string[] } }): string[] {
+  return (config.remote as any)?.publicVaults || [];
+}

package/src/tools/get-context.ts

@@ -10,7 +10,7 @@ import { resolveTemporalParams } from '../temporal.js';
 import { collectLinkedEntries } from '../linking.js';
 import { ok, err, errWithHint, kindIcon, fmtDate } from '../helpers.js';
 import { isEmbedAvailable } from '@context-vault/core/embed';
-import { getRemoteClient, getTeamId, mergeRemoteResults, mergeWithTeamResults } from '../remote.js';
+import { getRemoteClient, getTeamId, getPublicVaults, mergeRemoteResults, mergeWithTeamResults, mergeWithPublicResults } from '../remote.js';
 import type { LocalCtx, SharedCtx, ToolResult } from '../types.js';
 
 const STALE_DUPLICATE_DAYS = 7;
@@ -619,6 +619,34 @@ export async function handler(
     }
   }
 
+  // Public vault merge: query each configured public vault
+  const publicVaultSlugs = getPublicVaults(ctx.config);
+  if (remoteClient && publicVaultSlugs.length > 0 && (hasQuery || hasFilters)) {
+    const publicSearches = publicVaultSlugs.map(slug =>
+      remoteClient.publicSearch(slug, {
+        query: hasQuery ? query : undefined,
+        tags: effectiveTags.length ? effectiveTags : undefined,
+        kind: kindFilter || undefined,
+        category: scopedCategory || undefined,
+        limit: effectiveLimit,
+        since: effectiveSince || undefined,
+        until: effectiveUntil || undefined,
+      }).catch(e => {
+        console.warn(`[context-vault] Public vault "${slug}" search failed: ${(e as Error).message}`);
+        return [];
+      })
+    );
+    try {
+      const allPublicResults = await Promise.all(publicSearches);
+      const combined = allPublicResults.flat();
+      if (combined.length > 0) {
+        filtered = mergeWithPublicResults(filtered, combined as any[], effectiveLimit);
+      }
+    } catch (e) {
+      console.warn(`[context-vault] Public vault search failed: ${(e as Error).message}`);
+    }
+  }
+
   // Brief score boost: briefs rank slightly higher so consolidated snapshots
   // surface above the individual entries they summarize.
   for (const r of filtered) {

package/src/tools/recall.ts

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { ok } from '../helpers.js';
 import { isEmbedAvailable } from '@context-vault/core/embed';
 import { getAutoMemory, findAutoMemoryOverlaps } from '../auto-memory.js';
-import { getRemoteClient, getTeamId } from '../remote.js';
+import { getRemoteClient, getTeamId, getPublicVaults } from '../remote.js';
 import type { LocalCtx, SharedCtx, ToolResult } from '../types.js';
 
 const SEMANTIC_SIMILARITY_THRESHOLD = 0.6;
@@ -227,6 +227,40 @@ export async function handler(
     }
   }
 
+  // Public vault recall: query each configured public vault
+  const publicVaultSlugs = getPublicVaults(ctx.config);
+  if (remoteClient && publicVaultSlugs.length > 0 && hints.length < limit) {
+    const publicRecalls = publicVaultSlugs.map(slug =>
+      remoteClient.publicRecall(slug, {
+        signal,
+        signal_type,
+        bucket,
+        max_hints: limit - hints.length,
+      }).catch(e => {
+        console.warn(`[context-vault] Public vault "${slug}" recall failed: ${(e as Error).message}`);
+        return [];
+      })
+    );
+    try {
+      const allPublicHints = await Promise.all(publicRecalls);
+      const existingIds = new Set(hints.map(h => h.id));
+      for (const publicHints of allPublicHints) {
+        for (const ph of publicHints) {
+          if (hints.length >= limit) break;
+          if (existingIds.has(ph.id)) continue;
+          if (sessionSet && !bypassDedup && sessionSet.has(ph.id)) {
+            suppressed++;
+            continue;
+          }
+          hints.push({ ...ph, tags: [...(ph.tags || []), '[public]'] });
+          if (sessionSet) sessionSet.add(ph.id);
+        }
+      }
+    } catch (e) {
+      console.warn(`[context-vault] Public vault recall failed: ${(e as Error).message}`);
+    }
+  }
+
   let method: 'tag_match' | 'semantic' | 'none' = hints.length > 0 ? 'tag_match' : 'none';
 
   // Semantic fallback: when fast-path returns 0 results and signal is not file-based

package/src/tools/session-start.ts

@@ -5,7 +5,7 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { ok, err, ensureVaultExists, kindIcon, fmtDate } from '../helpers.js';
 import { getAutoMemory } from '../auto-memory.js';
-import { getRemoteClient, getTeamId } from '../remote.js';
+import { getRemoteClient, getTeamId, getPublicVaults } from '../remote.js';
 import type { AutoMemoryEntry, AutoMemoryResult } from '../auto-memory.js';
 import type { LocalCtx, SharedCtx, ToolResult } from '../types.js';
 
@@ -314,6 +314,50 @@ export async function handler(
     }
   }
 
+  // Public vault entries: include public knowledge if publicVaults are configured
+  let publicCount = 0;
+  const publicVaultSlugs = getPublicVaults(ctx.config);
+  if (remoteClient && publicVaultSlugs.length > 0 && tokensUsed < tokenBudget) {
+    try {
+      const allPublicSeenIds = new Set([
+        ...decisions.map((d: any) => d.id),
+        ...deduped.map((d: any) => d.id),
+        ...(lastSession ? [lastSession.id] : []),
+      ]);
+      const publicSearches = publicVaultSlugs.map(slug =>
+        remoteClient.publicSearch(slug, {
+          tags: effectiveTags.length ? effectiveTags : undefined,
+          limit: 5,
+          since: sinceDate,
+        }).catch(() => [])
+      );
+      const allPublicResults = await Promise.all(publicSearches);
+      const flatPublic = allPublicResults.flat().filter((r: any) => !allPublicSeenIds.has(r.id));
+      if (flatPublic.length > 0) {
+        const header = '## Public Knowledge\n';
+        const headerTokens = estimateTokens(header);
+        if (tokensUsed + headerTokens <= tokenBudget) {
+          const entryLines: string[] = [];
+          tokensUsed += headerTokens;
+          for (const entry of flatPublic) {
+            const slug = (entry as any).vault_slug || 'public';
+            const line = formatEntry(entry) + ` \`[public:${slug}]\``;
+            const lineTokens = estimateTokens(line);
+            if (tokensUsed + lineTokens > tokenBudget) break;
+            entryLines.push(line);
+            tokensUsed += lineTokens;
+            publicCount++;
+          }
+          if (entryLines.length > 0) {
+            sections.push(header + entryLines.join('\n') + '\n');
+          }
+        }
+      }
+    } catch (e) {
+      console.warn(`[context-vault] Public vault session_start failed: ${(e as Error).message}`);
+    }
+  }
+
   const totalEntries =
     (lastSession ? 1 : 0) +
     decisions.length +
@@ -321,7 +365,8 @@ export async function handler(
       return true;
     }).length +
     remoteCount +
-    teamCount;
+    teamCount +
+    publicCount;
 
   if (indexWarning) {
     sections.push(indexWarning);