@moxxy/plugin-memory 0.27.0

package/src/embedding-cache.test.ts

@@ -0,0 +1,268 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import type { EmbeddingProvider } from '@moxxy/sdk';
+import { EmbeddingIndex } from './embedding-cache.js';
+import { MemoryStore } from './store.js';
+
+let tmp: string;
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-cache-'));
+});
+afterEach(async () => {
+  await fs.rm(tmp, { recursive: true, force: true });
+});
+
+describe('EmbeddingIndex', () => {
+  it('returns null on lookup before load()', () => {
+    const idx = new EmbeddingIndex(tmp, 'test');
+    expect(idx.lookup('foo', 'body')).toBeNull();
+  });
+
+  it('round-trips a vector through flush+load', async () => {
+    const a = new EmbeddingIndex(tmp, 'test');
+    a.set('foo', 'body text', [0.1, 0.2, 0.3]);
+    await a.flush();
+
+    const b = new EmbeddingIndex(tmp, 'test');
+    await b.load();
+    expect(b.lookup('foo', 'body text')).toEqual([0.1, 0.2, 0.3]);
+  });
+
+  it('returns null when body hash changes (stale entry)', async () => {
+    const a = new EmbeddingIndex(tmp, 'test');
+    a.set('foo', 'original', [1, 2, 3]);
+    await a.flush();
+
+    const b = new EmbeddingIndex(tmp, 'test');
+    await b.load();
+    expect(b.lookup('foo', 'changed body')).toBeNull();
+  });
+
+  it('invalidates cache when embedder name changes', async () => {
+    const a = new EmbeddingIndex(tmp, 'openai');
+    a.set('foo', 'body', [1, 2, 3]);
+    await a.flush();
+
+    const b = new EmbeddingIndex(tmp, 'transformers');
+    await b.load();
+    expect(b.lookup('foo', 'body')).toBeNull();
+  });
+
+  it('invalidates cache when the dim changes under the same embedder name', async () => {
+    // Same name (e.g. the OpenAI embedder's coarse name), different dim — a
+    // model switch (1536 → 3072) must NOT reuse incomparable vectors.
+    const a = new EmbeddingIndex(tmp, 'openai', 1536);
+    a.set('foo', 'body', [1, 2, 3]);
+    await a.flush();
+
+    const b = new EmbeddingIndex(tmp, 'openai', 3072);
+    await b.load();
+    expect(b.lookup('foo', 'body')).toBeNull();
+
+    // Same name AND dim → cache is reused.
+    const c = new EmbeddingIndex(tmp, 'openai', 1536);
+    await c.load();
+    expect(c.lookup('foo', 'body')).toEqual([1, 2, 3]);
+  });
+
+  it('prune() removes entries not in the current set', async () => {
+    const idx = new EmbeddingIndex(tmp, 'test');
+    idx.set('keep', 'b1', [1]);
+    idx.set('drop', 'b2', [2]);
+    idx.prune(['keep']);
+    await idx.flush();
+
+    const reloaded = new EmbeddingIndex(tmp, 'test');
+    await reloaded.load();
+    expect(reloaded.lookup('keep', 'b1')).toEqual([1]);
+    expect(reloaded.lookup('drop', 'b2')).toBeNull();
+  });
+
+  it('flush() is a no-op when nothing changed', async () => {
+    const idx = new EmbeddingIndex(tmp, 'test');
+    await idx.load(); // no file yet
+    await idx.flush();
+    await expect(fs.access(path.join(tmp, '.embeddings.json'))).rejects.toThrow();
+  });
+
+  it('reads the cache file at most once across repeated load() calls', async () => {
+    const seed = new EmbeddingIndex(tmp, 'test');
+    seed.set('foo', 'body', [1, 2, 3]);
+    await seed.flush();
+
+    const idx = new EmbeddingIndex(tmp, 'test');
+    const readSpy = vi.spyOn(fs, 'readFile');
+    await idx.load();
+    await idx.load();
+    await idx.load();
+    expect(readSpy.mock.calls.length).toBe(1);
+    // The in-memory cache is still consulted after the single read.
+    expect(idx.lookup('foo', 'body')).toEqual([1, 2, 3]);
+    readSpy.mockRestore();
+  });
+
+  it('does not re-read after an initial miss (no file on disk)', async () => {
+    const idx = new EmbeddingIndex(tmp, 'test');
+    const readSpy = vi.spyOn(fs, 'readFile');
+    await idx.load(); // ENOENT
+    await idx.load();
+    expect(readSpy.mock.calls.length).toBe(1);
+    readSpy.mockRestore();
+  });
+
+  it('degrades a corrupt (unparseable) cache file to a cold cache instead of throwing', async () => {
+    await fs.writeFile(path.join(tmp, '.embeddings.json'), '{ this is not valid json ', 'utf8');
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const idx = new EmbeddingIndex(tmp, 'test');
+    try {
+      await expect(idx.load()).resolves.toBeUndefined(); // never throws
+      expect(idx.lookup('anything', 'body')).toBeNull(); // cold cache
+      expect(warn).toHaveBeenCalled();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('degrades a structurally-valid-but-shapeless cache file (no entries) to a cold cache', async () => {
+    // {version,embedder} with no `entries` previously threw a TypeError at
+    // Object.entries(undefined), permanently breaking every recall.
+    await fs.writeFile(
+      path.join(tmp, '.embeddings.json'),
+      JSON.stringify({ version: 1, embedder: 'test' }),
+      'utf8',
+    );
+    const idx = new EmbeddingIndex(tmp, 'test');
+    await expect(idx.load()).resolves.toBeUndefined();
+    expect(idx.lookup('foo', 'body')).toBeNull();
+  });
+
+  it('skips malformed entries but keeps the well-formed ones', async () => {
+    await fs.writeFile(
+      path.join(tmp, '.embeddings.json'),
+      JSON.stringify({
+        version: 1,
+        embedder: 'test',
+        entries: {
+          good: { hash: EmbeddingIndex.hash('body'), vector: [1, 2, 3] },
+          bad: { hash: 42, vector: 'not-an-array' },
+          alsoBad: { vector: [1, 2] }, // missing hash
+        },
+      }),
+      'utf8',
+    );
+    const idx = new EmbeddingIndex(tmp, 'test');
+    await idx.load();
+    expect(idx.lookup('good', 'body')).toEqual([1, 2, 3]);
+    expect(idx.lookup('bad', 'body')).toBeNull();
+    expect(idx.lookup('alsoBad', 'body')).toBeNull();
+  });
+});
+
+describe('MemoryStore vector recall with persistent index', () => {
+  const makeCountingEmbedder = (): EmbeddingProvider & { calls: number; embed: ReturnType<typeof vi.fn> } => {
+    const state = { calls: 0 };
+    const embed = vi.fn(async (texts: ReadonlyArray<string>) => {
+      state.calls += texts.length;
+      // Deterministic per-text vector: hash → 3 small floats
+      return texts.map((t) => {
+        const code = t.split('').reduce((acc, c) => acc + c.charCodeAt(0), 0);
+        return [code / 1000, (code * 7) % 1, (code * 13) % 1];
+      });
+    });
+    return Object.assign(
+      { name: 'counting', dim: 3 as const, embed },
+      {
+        get calls() {
+          return state.calls;
+        },
+      },
+    );
+  };
+
+  it('first recall embeds the full corpus + query', async () => {
+    const embedder = makeCountingEmbedder();
+    const store = new MemoryStore({ dir: tmp, embedder });
+    await store.save({ name: 'a', type: 'fact', description: 'A', body: 'body A' });
+    await store.save({ name: 'b', type: 'fact', description: 'B', body: 'body B' });
+    embedder.embed.mockClear();
+    await store.recall('q');
+    // 2 entries + 1 query
+    const totalEmbeds = embedder.embed.mock.calls.reduce(
+      (sum, call) => sum + (call[0] as string[]).length,
+      0,
+    );
+    expect(totalEmbeds).toBe(3);
+  });
+
+  it('second recall with unchanged corpus only embeds the new query', async () => {
+    const embedder = makeCountingEmbedder();
+    const store = new MemoryStore({ dir: tmp, embedder });
+    await store.save({ name: 'a', type: 'fact', description: 'A', body: 'body A' });
+    await store.save({ name: 'b', type: 'fact', description: 'B', body: 'body B' });
+
+    await store.recall('first query');   // populates cache
+    embedder.embed.mockClear();
+    await store.recall('second query');  // should only re-embed the new query
+
+    const totalEmbeds = embedder.embed.mock.calls.reduce(
+      (sum, call) => sum + (call[0] as string[]).length,
+      0,
+    );
+    expect(totalEmbeds).toBe(1);
+  });
+
+  it('changing one entry re-embeds only that one + query', async () => {
+    const embedder = makeCountingEmbedder();
+    const store = new MemoryStore({ dir: tmp, embedder });
+    await store.save({ name: 'a', type: 'fact', description: 'A', body: 'body A' });
+    await store.save({ name: 'b', type: 'fact', description: 'B', body: 'body B' });
+
+    await store.recall('q');
+    embedder.embed.mockClear();
+    await store.update('a', { body: 'CHANGED body A' });
+    await store.recall('q');
+
+    const totalEmbeds = embedder.embed.mock.calls.reduce(
+      (sum, call) => sum + (call[0] as string[]).length,
+      0,
+    );
+    // 'a' changed → re-embed; 'b' unchanged → cached; query → fresh. Total = 2.
+    expect(totalEmbeds).toBe(2);
+  });
+
+  it('persists across MemoryStore instances (cache survives process restart)', async () => {
+    const e1 = makeCountingEmbedder();
+    const s1 = new MemoryStore({ dir: tmp, embedder: e1 });
+    await s1.save({ name: 'a', type: 'fact', description: 'A', body: 'body A' });
+    await s1.recall('q');
+
+    const e2 = makeCountingEmbedder();
+    const s2 = new MemoryStore({ dir: tmp, embedder: e2 });
+    e2.embed.mockClear();
+    await s2.recall('q2');
+
+    // s2's cache loads from disk → only embeds the new query
+    const totalEmbeds = e2.embed.mock.calls.reduce(
+      (sum, call) => sum + (call[0] as string[]).length,
+      0,
+    );
+    expect(totalEmbeds).toBe(1);
+  });
+
+  it('persistEmbeddings: false disables caching even for neural embedders', async () => {
+    const embedder = makeCountingEmbedder();
+    const store = new MemoryStore({ dir: tmp, embedder, persistEmbeddings: false });
+    await store.save({ name: 'a', type: 'fact', description: 'A', body: 'body A' });
+    await store.recall('q');
+    embedder.embed.mockClear();
+    await store.recall('q');
+    // No cache → re-embeds everything
+    const totalEmbeds = embedder.embed.mock.calls.reduce(
+      (sum, call) => sum + (call[0] as string[]).length,
+      0,
+    );
+    expect(totalEmbeds).toBe(2); // 1 entry + 1 query
+  });
+});

package/src/embedding-cache.ts

@@ -0,0 +1,156 @@
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { writeFileAtomic } from '@moxxy/sdk/server';
+
+const INDEX_FILE = '.embeddings.json';
+const INDEX_VERSION = 1;
+
+interface IndexFile {
+  readonly version: typeof INDEX_VERSION;
+  readonly embedder: string;
+  /** Vector dimensionality the cache was built with (undefined = pre-dim format). */
+  readonly dim?: number | 'dynamic';
+  readonly entries: Record<string, IndexEntry>;
+}
+
+interface IndexEntry {
+  readonly hash: string;
+  readonly vector: ReadonlyArray<number>;
+}
+
+/**
+ * Persists computed embeddings to `<memoryDir>/.embeddings.json` keyed by
+ * content hash. The cache is invalidated when the embedder name OR its
+ * dimensionality changes — a name alone is too coarse (e.g. the OpenAI embedder
+ * reports a fixed name across models/`dimensions` settings, so a 1536→3072
+ * model switch must invalidate on the dim mismatch or recall compares
+ * incomparable vectors).
+ */
+export class EmbeddingIndex {
+  private cache: Map<string, IndexEntry> = new Map();
+  private dirty = false;
+  private loaded = false;
+
+  constructor(
+    private readonly dir: string,
+    private readonly embedderName: string,
+    private readonly dim?: number | 'dynamic',
+  ) {}
+
+  static hash(text: string): string {
+    return createHash('sha256').update(text).digest('hex').slice(0, 24);
+  }
+
+  private get filePath(): string {
+    return path.join(this.dir, INDEX_FILE);
+  }
+
+  async load(): Promise<void> {
+    // Read the on-disk cache at most once per instance. The store memoizes this
+    // index for its lifetime and is the single writer (flush() keeps disk in
+    // sync for our own writes), so re-reading + re-parsing the whole file on
+    // every recall is pure overhead — the in-memory Map is already authoritative.
+    if (this.loaded) return;
+    let raw: string;
+    try {
+      raw = await fs.readFile(this.filePath, 'utf8');
+    } catch (err) {
+      if (!isEnoent(err)) throw err;
+      // No file on disk yet — still treat as loaded so subsequent recalls don't
+      // re-stat. This process is the single writer; flush() creates the file.
+      this.loaded = true;
+      return;
+    }
+    // The cache is a pure optimization: a corrupt/garbled/half-synced file
+    // (truncated JSON, manual edit, partial cloud-drive sync, schema drift) must
+    // degrade to a COLD cache, never permanently break every recall. Parse and
+    // shape-check defensively; on any failure, log and start empty.
+    this.loaded = true;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      console.warn(`[plugin-memory] ignoring corrupt embedding cache (${this.filePath}): ${String(err)}`);
+      return;
+    }
+    if (!isValidIndexFile(parsed)) return; // malformed shape → cold cache
+    if (parsed.version !== INDEX_VERSION) return; // unknown format, ignore
+    if (parsed.embedder !== this.embedderName) return; // embedder changed, invalidate
+    // Dim mismatch (incl. an old file written before dim was tracked) → the
+    // vectors are a different dimensionality; invalidate rather than mix them.
+    if (this.dim !== undefined && parsed.dim !== this.dim) return;
+    for (const [name, entry] of Object.entries(parsed.entries)) {
+      if (isValidIndexEntry(entry)) this.cache.set(name, entry);
+    }
+  }
+
+  /**
+   * For a `(name, body)` pair, return either the cached vector (if the body
+   * hash matches) or `null` (miss). Callers re-embed the misses and call
+   * `set()` with the fresh vectors.
+   */
+  lookup(name: string, body: string): ReadonlyArray<number> | null {
+    const entry = this.cache.get(name);
+    if (!entry) return null;
+    if (entry.hash !== EmbeddingIndex.hash(body)) return null;
+    return entry.vector;
+  }
+
+  set(name: string, body: string, vector: ReadonlyArray<number>): void {
+    const hash = EmbeddingIndex.hash(body);
+    const existing = this.cache.get(name);
+    if (existing && existing.hash === hash) return;
+    this.cache.set(name, { hash, vector });
+    this.dirty = true;
+  }
+
+  /** Drop entries that no longer correspond to existing memories. */
+  prune(currentNames: ReadonlyArray<string>): void {
+    const wanted = new Set(currentNames);
+    for (const name of [...this.cache.keys()]) {
+      if (!wanted.has(name)) {
+        this.cache.delete(name);
+        this.dirty = true;
+      }
+    }
+  }
+
+  async flush(): Promise<void> {
+    if (!this.dirty) return;
+    const data: IndexFile = {
+      version: INDEX_VERSION,
+      embedder: this.embedderName,
+      ...(this.dim !== undefined ? { dim: this.dim } : {}),
+      entries: Object.fromEntries(this.cache),
+    };
+    await writeFileAtomic(this.filePath, JSON.stringify(data), { mode: 0o600 });
+    this.dirty = false;
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+}
+
+function isEnoent(err: unknown): boolean {
+  return err instanceof Error && 'code' in err && (err as NodeJS.ErrnoException).code === 'ENOENT';
+}
+
+/** Structural guard so a valid-JSON-but-wrong-shape file (e.g. a missing
+ *  `entries`) degrades to a cold cache instead of throwing in load(). */
+function isValidIndexFile(value: unknown): value is IndexFile {
+  if (typeof value !== 'object' || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return typeof v.entries === 'object' && v.entries !== null;
+}
+
+function isValidIndexEntry(value: unknown): value is IndexEntry {
+  if (typeof value !== 'object' || value === null) return false;
+  const e = value as Record<string, unknown>;
+  return (
+    typeof e.hash === 'string' &&
+    Array.isArray(e.vector) &&
+    e.vector.every((n) => typeof n === 'number')
+  );
+}

package/src/index.test.ts

@@ -0,0 +1,67 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import type { ToolDef } from '@moxxy/sdk';
+import { buildMemoryPlugin } from './index.js';
+import { MemoryStore } from './store.js';
+
+let tmp: string;
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-idx-'));
+});
+afterEach(async () => {
+  await fs.rm(tmp, { recursive: true, force: true });
+});
+
+const toolByName = (name: string): ToolDef => {
+  const { plugin } = buildMemoryPlugin({ dir: tmp });
+  const tool = plugin.tools?.find((t) => t.name === name);
+  if (!tool) throw new Error(`tool ${name} not registered`);
+  return tool;
+};
+
+describe('memory tool input schemas reject path-traversal names', () => {
+  // The inproc isolator does NOT enforce the fs.write glob, so these Zod
+  // schemas are the sole guard preventing a hallucinated/hostile `name` from
+  // reaching fs.unlink / fs.readFile outside the memory dir.
+  const traversals = ['../../../etc/passwd', '../escape', 'a/b', '/abs/path', '..', '.hidden', 'Has Space'];
+
+  it.each(['memory_forget', 'memory_update'])('%s rejects traversal names', (toolName) => {
+    const schema = toolByName(toolName).inputSchema;
+    for (const name of traversals) {
+      expect(schema.safeParse({ name }).success).toBe(false);
+    }
+    // A clean slug still parses.
+    expect(schema.safeParse({ name: 'valid-slug-1' }).success).toBe(true);
+  });
+});
+
+describe('MemoryStore path containment (belt-and-suspenders)', () => {
+  it('forget refuses a traversal name instead of unlinking outside the dir', async () => {
+    const store = new MemoryStore({ dir: tmp });
+    // Plant a sentinel file OUTSIDE the memory dir.
+    const outside = path.join(tmp, '..', `sentinel-${path.basename(tmp)}.md`);
+    await fs.writeFile(outside, 'do not delete');
+    try {
+      await expect(store.forget('../' + path.basename(outside).replace(/\.md$/, ''))).rejects.toThrow(
+        /invalid memory name/,
+      );
+      // Sentinel survives.
+      await expect(fs.access(outside)).resolves.toBeUndefined();
+    } finally {
+      await fs.rm(outside, { force: true });
+    }
+  });
+
+  it('get refuses a name with embedded separators', async () => {
+    const store = new MemoryStore({ dir: tmp });
+    await expect(store.get('nested/name')).rejects.toThrow(/invalid memory name/);
+  });
+
+  it('round-trips a clean slug name unchanged', async () => {
+    const store = new MemoryStore({ dir: tmp });
+    await store.save({ name: 'clean-slug', type: 'fact', description: 'd', body: 'b' });
+    expect((await store.get('clean-slug'))?.frontmatter.name).toBe('clean-slug');
+  });
+});