memorix 1.2.0 → 1.2.2

package/src/memory/freshness.ts

@@ -1,122 +1,122 @@
-/**
- * Unified Freshness Gate (Phase 3a)
- *
- * Replaces withFreshObservations() as the public API for all retrieval
- * surfaces. Checks both observation and mini-skill generation counters
- * to ensure the Orama index is fully up-to-date before any read.
- *
- * withFreshObservations() remains in observations.ts as @internal —
- * only called by this module and legacy test code.
- */
-
-import { ensureFreshObservations } from './observations.js';
-import { getMiniSkillStore, isMiniSkillStoreInitialized } from '../store/mini-skill-store.js';
-import { miniSkillToDocument } from '../skills/mini-skills.js';
-import { insert, remove } from '@orama/orama';
-
-// ── Mini-skill index state ──────────────────────────────────────
-
-let lastMiniSkillGeneration = -1;
-
-/**
- * Check if mini-skills have changed since our last index sync.
- * If stale, reindex all mini-skills in Orama.
- *
- * Returns true if the index was refreshed.
- */
-export async function ensureFreshMiniSkills(): Promise<boolean> {
-  // Skip silently when the store has not been initialized yet —
-  // observation-only paths never call initMiniSkillStore().
-  if (!isMiniSkillStoreInitialized()) return false;
-
-  try {
-    const store = getMiniSkillStore();
-    const wasStale = await store.ensureFresh();
-    const currentGen = store.getGeneration();
-
-    if (wasStale || currentGen !== lastMiniSkillGeneration) {
-      await reindexMiniSkills();
-      lastMiniSkillGeneration = currentGen;
-      return true;
-    }
-  } catch (err) {
-    // Best-effort — don't crash the read path, but log for diagnostics
-    console.warn(`[memorix] ensureFreshMiniSkills failed: ${err instanceof Error ? err.message : err}`);
-  }
-  return false;
-}
-
-// Deterministic tracking of indexed mini-skill doc IDs — avoids empty-term search
-const indexedSkillDocIds = new Set<string>();
-
-/**
- * Reindex all mini-skills into the Orama database.
- * Uses deterministic doc ID tracking instead of empty-term search to ensure
- * all stale documents are removed reliably.
- */
-export async function reindexMiniSkills(): Promise<number> {
-  // Lazy import to avoid circular dependency
-  const { getDb } = await import('../store/orama-store.js');
-  const database = await getDb();
-
-  // Remove previously tracked mini-skill documents by their known IDs
-  for (const docId of indexedSkillDocIds) {
-    try { await remove(database, docId); } catch { /* already removed or never existed */ }
-  }
-  indexedSkillDocIds.clear();
-
-  // Load and index all current mini-skills
-  const store = getMiniSkillStore();
-  const skills = await store.loadAll();
-  let indexed = 0;
-
-  for (const skill of skills) {
-    try {
-      const doc = miniSkillToDocument(skill);
-      await insert(database, doc);
-      indexedSkillDocIds.add(doc.id);
-      indexed++;
-    } catch (err) {
-      console.error(`[memorix] Failed to index mini-skill ${skill.id}: ${err instanceof Error ? err.message : err}`);
-    }
-  }
-
-  return indexed;
-}
-
-// ── Unified gate ────────────────────────────────────────────────
-
-/**
- * Ensure both observations and mini-skills are fresh in the Orama index.
- * Returns true if any data source was refreshed.
- */
-export async function ensureFreshIndex(): Promise<boolean> {
-  let anyStale = false;
-  const obsStale = await ensureFreshObservations();
-  if (obsStale) anyStale = true;
-  const skillsStale = await ensureFreshMiniSkills();
-  if (skillsStale) anyStale = true;
-  return anyStale;
-}
-
-/**
- * Centralized freshness gate — wraps a read-facing function with
- * ensureFreshIndex() so callers cannot forget the freshness check.
- *
- * Usage:
- *   return withFreshIndex(async () => { ... read from Orama ... });
- *
- * Phase 3a: replaces withFreshObservations() at all retrieval call sites.
- */
-export async function withFreshIndex<T>(fn: () => T | Promise<T>): Promise<T> {
-  await ensureFreshIndex();
-  return fn();
-}
-
-/**
- * Reset mini-skill freshness tracking. Used in tests.
- */
-export function resetMiniSkillFreshness(): void {
-  lastMiniSkillGeneration = -1;
-  indexedSkillDocIds.clear();
-}
+/**
+ * Unified Freshness Gate (Phase 3a)
+ *
+ * Replaces withFreshObservations() as the public API for all retrieval
+ * surfaces. Checks both observation and mini-skill generation counters
+ * to ensure the Orama index is fully up-to-date before any read.
+ *
+ * withFreshObservations() remains in observations.ts as @internal —
+ * only called by this module and legacy test code.
+ */
+
+import { ensureFreshObservations } from './observations.js';
+import { getMiniSkillStore, isMiniSkillStoreInitialized } from '../store/mini-skill-store.js';
+import { miniSkillToDocument } from '../skills/mini-skills.js';
+import { insert, remove } from '@orama/orama';
+
+// ── Mini-skill index state ──────────────────────────────────────
+
+let lastMiniSkillGeneration = -1;
+
+/**
+ * Check if mini-skills have changed since our last index sync.
+ * If stale, reindex all mini-skills in Orama.
+ *
+ * Returns true if the index was refreshed.
+ */
+export async function ensureFreshMiniSkills(): Promise<boolean> {
+  // Skip silently when the store has not been initialized yet —
+  // observation-only paths never call initMiniSkillStore().
+  if (!isMiniSkillStoreInitialized()) return false;
+
+  try {
+    const store = getMiniSkillStore();
+    const wasStale = await store.ensureFresh();
+    const currentGen = store.getGeneration();
+
+    if (wasStale || currentGen !== lastMiniSkillGeneration) {
+      await reindexMiniSkills();
+      lastMiniSkillGeneration = currentGen;
+      return true;
+    }
+  } catch (err) {
+    // Best-effort — don't crash the read path, but log for diagnostics
+    console.warn(`[memorix] ensureFreshMiniSkills failed: ${err instanceof Error ? err.message : err}`);
+  }
+  return false;
+}
+
+// Deterministic tracking of indexed mini-skill doc IDs — avoids empty-term search
+const indexedSkillDocIds = new Set<string>();
+
+/**
+ * Reindex all mini-skills into the Orama database.
+ * Uses deterministic doc ID tracking instead of empty-term search to ensure
+ * all stale documents are removed reliably.
+ */
+export async function reindexMiniSkills(): Promise<number> {
+  // Lazy import to avoid circular dependency
+  const { getDb } = await import('../store/orama-store.js');
+  const database = await getDb();
+
+  // Remove previously tracked mini-skill documents by their known IDs
+  for (const docId of indexedSkillDocIds) {
+    try { await remove(database, docId); } catch { /* already removed or never existed */ }
+  }
+  indexedSkillDocIds.clear();
+
+  // Load and index all current mini-skills
+  const store = getMiniSkillStore();
+  const skills = await store.loadAll();
+  let indexed = 0;
+
+  for (const skill of skills) {
+    try {
+      const doc = miniSkillToDocument(skill);
+      await insert(database, doc);
+      indexedSkillDocIds.add(doc.id);
+      indexed++;
+    } catch (err) {
+      console.error(`[memorix] Failed to index mini-skill ${skill.id}: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+
+  return indexed;
+}
+
+// ── Unified gate ────────────────────────────────────────────────
+
+/**
+ * Ensure both observations and mini-skills are fresh in the Orama index.
+ * Returns true if any data source was refreshed.
+ */
+export async function ensureFreshIndex(): Promise<boolean> {
+  let anyStale = false;
+  const obsStale = await ensureFreshObservations();
+  if (obsStale) anyStale = true;
+  const skillsStale = await ensureFreshMiniSkills();
+  if (skillsStale) anyStale = true;
+  return anyStale;
+}
+
+/**
+ * Centralized freshness gate — wraps a read-facing function with
+ * ensureFreshIndex() so callers cannot forget the freshness check.
+ *
+ * Usage:
+ *   return withFreshIndex(async () => { ... read from Orama ... });
+ *
+ * Phase 3a: replaces withFreshObservations() at all retrieval call sites.
+ */
+export async function withFreshIndex<T>(fn: () => T | Promise<T>): Promise<T> {
+  await ensureFreshIndex();
+  return fn();
+}
+
+/**
+ * Reset mini-skill freshness tracking. Used in tests.
+ */
+export function resetMiniSkillFreshness(): void {
+  lastMiniSkillGeneration = -1;
+  indexedSkillDocIds.clear();
+}

package/src/memory/graph-context.ts

@@ -1,6 +1,7 @@
 import { auditMemoryQuality, type MemoryQualityAuditReport } from './quality-audit.js';
 import type { Observation } from '../types.js';
 import { getRetentionZone } from './retention.js';
+import { isEligibleForAutomaticDelivery } from './admission.js';
 
 export interface GraphContextPacketOptions {
   projectId: string;
@@ -225,6 +226,8 @@ function scoreForPacket(obs: Observation, queryTokens: string[], referenceTime:
     source: obs.source ?? 'agent',
     sourceDetail: obs.sourceDetail ?? '',
     valueCategory: obs.valueCategory ?? '',
+    admissionState: obs.admissionState ?? '',
+    admissionReason: obs.admissionReason ?? '',
   }, referenceTime) !== 'active') {
     score -= 2;
   }
@@ -348,8 +351,11 @@ export function buildGraphContextPacket(
     ...audit.issues.orphans.map((entry) => entry.id),
     ...audit.issues.retentionCandidates.map((entry) => entry.id),
   ]);
-  const filteredObservations = observations.filter((obs) => obs.projectId === options.projectId && !riskIds.has(obs.id));
-  const baseObservations = filteredObservations.length > 0 ? filteredObservations : observations;
+  const deliveryEligible = observations.filter(
+    (obs) => obs.projectId === options.projectId && isEligibleForAutomaticDelivery(obs),
+  );
+  const filteredObservations = deliveryEligible.filter((obs) => !riskIds.has(obs.id));
+  const baseObservations = filteredObservations.length > 0 ? filteredObservations : deliveryEligible;
   const memories = pickMemories(baseObservations, options.projectId, options.query, options.limit ?? 5, referenceTime);
   const entities = buildEntities(memories);
   const entityNames = new Set(entities.map((entity) => entity.name));

package/src/memory/graph-scope.ts

@@ -0,0 +1,46 @@
+export interface GraphScopeObservation {
+  entityName?: string;
+  relatedEntities?: string[];
+  status?: string;
+}
+
+export interface ScopedKnowledgeGraph<Entity extends { name: string }, Relation extends { from: string; to: string }> {
+  entities: Entity[];
+  relations: Relation[];
+  entityNames: Set<string>;
+}
+
+/** Return the active project entities, including explicit cross-references. */
+export function projectGraphEntityNames(observations: readonly GraphScopeObservation[]): Set<string> {
+  const entityNames = new Set<string>();
+  for (const observation of observations) {
+    if ((observation.status ?? 'active') !== 'active') continue;
+    const entityName = observation.entityName?.trim();
+    if (entityName) entityNames.add(entityName);
+    for (const relatedEntity of observation.relatedEntities ?? []) {
+      const name = relatedEntity.trim();
+      if (name) entityNames.add(name);
+    }
+  }
+  return entityNames;
+}
+
+/**
+ * Give every graph surface the same project projection: active entities plus
+ * explicit related entities, with only edges whose endpoints remain visible.
+ */
+export function scopeKnowledgeGraphToProject<
+  Entity extends { name: string },
+  Relation extends { from: string; to: string },
+>(
+  graph: { entities: readonly Entity[]; relations: readonly Relation[] },
+  observations: readonly GraphScopeObservation[],
+): ScopedKnowledgeGraph<Entity, Relation> {
+  const entityNames = projectGraphEntityNames(observations);
+  const entities = graph.entities.filter(entity => entityNames.has(entity.name));
+  const visibleNames = new Set(entities.map(entity => entity.name));
+  const relations = graph.relations.filter(relation =>
+    visibleNames.has(relation.from) && visibleNames.has(relation.to),
+  );
+  return { entities, relations, entityNames };
+}