memorix 1.5.1 → 1.6.0

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.ts

@@ -1,197 +1,197 @@
-/**
- * Knowledge Graph Manager
- *
- * Manages the Entity-Relation knowledge graph.
- * Source: MCP Official Memory Server v0.6.3 (complete rewrite with same API).
- *
- * Key differences from official implementation:
- * - Uses per-project JSONL files (official uses single file)
- * - Async initialization with persistence layer
- * - Project-scoped operations
- */
-
-import type { Entity, Relation, KnowledgeGraph } from '../types.js';
-import { initGraphStore, getGraphStore } from '../store/graph-store.js';
-
-export class KnowledgeGraphManager {
-  private entities: Entity[] = [];
-  private relations: Relation[] = [];
-  private projectDir: string;
-  private initialized = false;
-  /** Index: lowercase entity name → Entity for O(1) lookups */
-  private entityIndex = new Map<string, Entity>();
-
-  constructor(projectDir: string) {
-    this.projectDir = projectDir;
-  }
-
-  /** Rebuild the entity name index */
-  private rebuildIndex(): void {
-    this.entityIndex.clear();
-    for (const e of this.entities) {
-      this.entityIndex.set(e.name.toLowerCase(), e);
-    }
-  }
-
-  /** Load graph from SQLite on first access */
-  async init(): Promise<void> {
-    if (this.initialized) return;
-    await initGraphStore(this.projectDir);
-    const store = getGraphStore();
-    this.entities = store.loadEntities();
-    this.relations = store.loadRelations();
-    this.rebuildIndex();
-    this.initialized = true;
-  }
-
-  /** Find entity by name (case-insensitive, O(1)) */
-  findEntityByName(name: string): Entity | undefined {
-    return this.entityIndex.get(name.toLowerCase());
-  }
-
-  /** Get all entity names as a Set (lowercase, for fast membership checks) */
-  getEntityNameSet(): Set<string> {
-    return new Set(this.entityIndex.keys());
-  }
-
-  /** Persist current state to SQLite */
-  private async save(): Promise<void> {
-    const store = getGraphStore();
-    store.replaceAll(this.entities, this.relations);
-  }
-
-  /** Create new entities (skip duplicates by name) */
-  async createEntities(entities: Entity[]): Promise<Entity[]> {
-    await this.init();
-    const newEntities = entities.filter(
-      (e) => !this.entityIndex.has(e.name.toLowerCase()),
-    );
-    this.entities.push(...newEntities);
-    if (newEntities.length > 0) this.rebuildIndex();
-    await this.save();
-    return newEntities;
-  }
-
-  /** Create new relations (skip duplicates) */
-  async createRelations(relations: Relation[]): Promise<Relation[]> {
-    await this.init();
-    const newRelations = relations.filter(
-      (r) =>
-        !this.relations.some(
-          (existing) =>
-            existing.from === r.from &&
-            existing.to === r.to &&
-            existing.relationType === r.relationType,
-        ),
-    );
-    this.relations.push(...newRelations);
-    await this.save();
-    return newRelations;
-  }
-
-  /** Add observations to existing entities */
-  async addObservations(
-    observations: { entityName: string; contents: string[] }[],
-  ): Promise<{ entityName: string; addedObservations: string[] }[]> {
-    await this.init();
-    const results = observations.map((o) => {
-      const entity = this.entities.find((e) => e.name === o.entityName);
-      if (!entity) {
-        throw new Error(`Entity with name ${o.entityName} not found`);
-      }
-      const newObs = o.contents.filter((c) => !entity.observations.includes(c));
-      entity.observations.push(...newObs);
-      return { entityName: o.entityName, addedObservations: newObs };
-    });
-    await this.save();
-    return results;
-  }
-
-  /** Delete entities and their associated relations */
-  async deleteEntities(entityNames: string[]): Promise<void> {
-    await this.init();
-    this.entities = this.entities.filter((e) => !entityNames.includes(e.name));
-    this.relations = this.relations.filter(
-      (r) => !entityNames.includes(r.from) && !entityNames.includes(r.to),
-    );
-    this.rebuildIndex();
-    await this.save();
-  }
-
-  /** Delete specific observations from entities */
-  async deleteObservations(
-    deletions: { entityName: string; observations: string[] }[],
-  ): Promise<void> {
-    await this.init();
-    for (const d of deletions) {
-      const entity = this.entities.find((e) => e.name === d.entityName);
-      if (entity) {
-        entity.observations = entity.observations.filter(
-          (o) => !d.observations.includes(o),
-        );
-      }
-    }
-    await this.save();
-  }
-
-  /** Delete specific relations */
-  async deleteRelations(relations: Relation[]): Promise<void> {
-    await this.init();
-    this.relations = this.relations.filter(
-      (r) =>
-        !relations.some(
-          (del) =>
-            r.from === del.from &&
-            r.to === del.to &&
-            r.relationType === del.relationType,
-        ),
-    );
-    await this.save();
-  }
-
-  /** Get all entity names (for Formation Pipeline entity resolution) */
-  getEntityNames(): string[] {
-    return this.entities.map(e => e.name);
-  }
-
-  /** Read the entire graph */
-  async readGraph(): Promise<KnowledgeGraph> {
-    await this.init();
-    return { entities: this.entities, relations: this.relations };
-  }
-
-  /** Search nodes by query string (upgraded from official's basic includes) */
-  async searchNodes(query: string): Promise<KnowledgeGraph> {
-    await this.init();
-    const lowerQuery = query.toLowerCase();
-
-    const filteredEntities = this.entities.filter(
-      (e) =>
-        e.name.toLowerCase().includes(lowerQuery) ||
-        e.entityType.toLowerCase().includes(lowerQuery) ||
-        e.observations.some((o) => o.toLowerCase().includes(lowerQuery)),
-    );
-
-    const filteredNames = new Set(filteredEntities.map((e) => e.name));
-
-    const filteredRelations = this.relations.filter(
-      (r) => filteredNames.has(r.from) && filteredNames.has(r.to),
-    );
-
-    return { entities: filteredEntities, relations: filteredRelations };
-  }
-
-  /** Open specific nodes by name */
-  async openNodes(names: string[]): Promise<KnowledgeGraph> {
-    await this.init();
-
-    const filteredEntities = this.entities.filter((e) => names.includes(e.name));
-    const filteredNames = new Set(filteredEntities.map((e) => e.name));
-
-    const filteredRelations = this.relations.filter(
-      (r) => filteredNames.has(r.from) && filteredNames.has(r.to),
-    );
-
-    return { entities: filteredEntities, relations: filteredRelations };
-  }
-}
+/**
+ * Knowledge Graph Manager
+ *
+ * Manages the Entity-Relation knowledge graph.
+ * Source: MCP Official Memory Server v0.6.3 (complete rewrite with same API).
+ *
+ * Key differences from official implementation:
+ * - Uses per-project JSONL files (official uses single file)
+ * - Async initialization with persistence layer
+ * - Project-scoped operations
+ */
+
+import type { Entity, Relation, KnowledgeGraph } from '../types.js';
+import { initGraphStore, getGraphStore } from '../store/graph-store.js';
+
+export class KnowledgeGraphManager {
+  private entities: Entity[] = [];
+  private relations: Relation[] = [];
+  private projectDir: string;
+  private initialized = false;
+  /** Index: lowercase entity name → Entity for O(1) lookups */
+  private entityIndex = new Map<string, Entity>();
+
+  constructor(projectDir: string) {
+    this.projectDir = projectDir;
+  }
+
+  /** Rebuild the entity name index */
+  private rebuildIndex(): void {
+    this.entityIndex.clear();
+    for (const e of this.entities) {
+      this.entityIndex.set(e.name.toLowerCase(), e);
+    }
+  }
+
+  /** Load graph from SQLite on first access */
+  async init(): Promise<void> {
+    if (this.initialized) return;
+    await initGraphStore(this.projectDir);
+    const store = getGraphStore();
+    this.entities = store.loadEntities();
+    this.relations = store.loadRelations();
+    this.rebuildIndex();
+    this.initialized = true;
+  }
+
+  /** Find entity by name (case-insensitive, O(1)) */
+  findEntityByName(name: string): Entity | undefined {
+    return this.entityIndex.get(name.toLowerCase());
+  }
+
+  /** Get all entity names as a Set (lowercase, for fast membership checks) */
+  getEntityNameSet(): Set<string> {
+    return new Set(this.entityIndex.keys());
+  }
+
+  /** Persist current state to SQLite */
+  private async save(): Promise<void> {
+    const store = getGraphStore();
+    store.replaceAll(this.entities, this.relations);
+  }
+
+  /** Create new entities (skip duplicates by name) */
+  async createEntities(entities: Entity[]): Promise<Entity[]> {
+    await this.init();
+    const newEntities = entities.filter(
+      (e) => !this.entityIndex.has(e.name.toLowerCase()),
+    );
+    this.entities.push(...newEntities);
+    if (newEntities.length > 0) this.rebuildIndex();
+    await this.save();
+    return newEntities;
+  }
+
+  /** Create new relations (skip duplicates) */
+  async createRelations(relations: Relation[]): Promise<Relation[]> {
+    await this.init();
+    const newRelations = relations.filter(
+      (r) =>
+        !this.relations.some(
+          (existing) =>
+            existing.from === r.from &&
+            existing.to === r.to &&
+            existing.relationType === r.relationType,
+        ),
+    );
+    this.relations.push(...newRelations);
+    await this.save();
+    return newRelations;
+  }
+
+  /** Add observations to existing entities */
+  async addObservations(
+    observations: { entityName: string; contents: string[] }[],
+  ): Promise<{ entityName: string; addedObservations: string[] }[]> {
+    await this.init();
+    const results = observations.map((o) => {
+      const entity = this.entities.find((e) => e.name === o.entityName);
+      if (!entity) {
+        throw new Error(`Entity with name ${o.entityName} not found`);
+      }
+      const newObs = o.contents.filter((c) => !entity.observations.includes(c));
+      entity.observations.push(...newObs);
+      return { entityName: o.entityName, addedObservations: newObs };
+    });
+    await this.save();
+    return results;
+  }
+
+  /** Delete entities and their associated relations */
+  async deleteEntities(entityNames: string[]): Promise<void> {
+    await this.init();
+    this.entities = this.entities.filter((e) => !entityNames.includes(e.name));
+    this.relations = this.relations.filter(
+      (r) => !entityNames.includes(r.from) && !entityNames.includes(r.to),
+    );
+    this.rebuildIndex();
+    await this.save();
+  }
+
+  /** Delete specific observations from entities */
+  async deleteObservations(
+    deletions: { entityName: string; observations: string[] }[],
+  ): Promise<void> {
+    await this.init();
+    for (const d of deletions) {
+      const entity = this.entities.find((e) => e.name === d.entityName);
+      if (entity) {
+        entity.observations = entity.observations.filter(
+          (o) => !d.observations.includes(o),
+        );
+      }
+    }
+    await this.save();
+  }
+
+  /** Delete specific relations */
+  async deleteRelations(relations: Relation[]): Promise<void> {
+    await this.init();
+    this.relations = this.relations.filter(
+      (r) =>
+        !relations.some(
+          (del) =>
+            r.from === del.from &&
+            r.to === del.to &&
+            r.relationType === del.relationType,
+        ),
+    );
+    await this.save();
+  }
+
+  /** Get all entity names (for Formation Pipeline entity resolution) */
+  getEntityNames(): string[] {
+    return this.entities.map(e => e.name);
+  }
+
+  /** Read the entire graph */
+  async readGraph(): Promise<KnowledgeGraph> {
+    await this.init();
+    return { entities: this.entities, relations: this.relations };
+  }
+
+  /** Search nodes by query string (upgraded from official's basic includes) */
+  async searchNodes(query: string): Promise<KnowledgeGraph> {
+    await this.init();
+    const lowerQuery = query.toLowerCase();
+
+    const filteredEntities = this.entities.filter(
+      (e) =>
+        e.name.toLowerCase().includes(lowerQuery) ||
+        e.entityType.toLowerCase().includes(lowerQuery) ||
+        e.observations.some((o) => o.toLowerCase().includes(lowerQuery)),
+    );
+
+    const filteredNames = new Set(filteredEntities.map((e) => e.name));
+
+    const filteredRelations = this.relations.filter(
+      (r) => filteredNames.has(r.from) && filteredNames.has(r.to),
+    );
+
+    return { entities: filteredEntities, relations: filteredRelations };
+  }
+
+  /** Open specific nodes by name */
+  async openNodes(names: string[]): Promise<KnowledgeGraph> {
+    await this.init();
+
+    const filteredEntities = this.entities.filter((e) => names.includes(e.name));
+    const filteredNames = new Set(filteredEntities.map((e) => e.name));
+
+    const filteredRelations = this.relations.filter(
+      (r) => filteredNames.has(r.from) && filteredNames.has(r.to),
+    );
+
+    return { entities: filteredEntities, relations: filteredRelations };
+  }
+}