@moxxy/plugin-memory 0.27.0

package/src/store/search.test.ts

@@ -0,0 +1,185 @@
+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, Mutex } from '@moxxy/sdk';
+import { createMutex } from '@moxxy/sdk';
+import { rankByKeywords, recallVector } from './search.js';
+import { EmbeddingIndex } from '../embedding-cache.js';
+import type { MemoryEntry, MemoryType } from './types.js';
+
+function entry(
+  name: string,
+  description: string,
+  body: string,
+  opts: { type?: MemoryType; tags?: string[] } = {},
+): MemoryEntry {
+  return {
+    frontmatter: {
+      name,
+      type: opts.type ?? 'fact',
+      description,
+      ...(opts.tags ? { tags: opts.tags } : {}),
+    },
+    body,
+    path: `/tmp/${name}.md`,
+  };
+}
+
+describe('rankByKeywords', () => {
+  it('counts repeated occurrences in the body (no array-split regression)', () => {
+    // "deploy" appears 3x in the body; the non-allocating indexOf count must
+    // match the old `split(t).length - 1` behavior exactly.
+    const e = entry('ci', 'continuous integration', 'deploy then deploy and deploy again');
+    const ranked = rankByKeywords([e], 'deploy', 5);
+    expect(ranked).toHaveLength(1);
+    expect(ranked[0]!.score).toBe(3);
+  });
+
+  it('weights name and description hits above body-only hits', () => {
+    const named = entry('deploy-runbook', 'how to ship', 'steps here');
+    const described = entry('runbook', 'deploy guide', 'steps here');
+    const bodyOnly = entry('notes', 'misc', 'we deploy on fridays');
+    const ranked = rankByKeywords([bodyOnly, described, named], 'deploy', 5);
+    // name match (+3) > description match (+2) > body-only (+1)
+    expect(ranked.map((r) => r.entry.frontmatter.name)).toEqual([
+      'deploy-runbook',
+      'runbook',
+      'notes',
+    ]);
+  });
+
+  it('sums scores across multiple query tokens and ranks by total', () => {
+    const both = entry('a', 'alpha beta', 'alpha beta gamma');
+    const one = entry('b', 'just alpha', 'nothing else');
+    const ranked = rankByKeywords([one, both], 'alpha beta', 5);
+    expect(ranked[0]!.entry.frontmatter.name).toBe('a');
+  });
+
+  it('drops zero-score entries and respects the limit', () => {
+    const hit = entry('x', 'has the word widget', 'widget widget');
+    const miss = entry('y', 'unrelated', 'nothing relevant');
+    const ranked = rankByKeywords([hit, miss], 'widget', 1);
+    expect(ranked).toHaveLength(1);
+    expect(ranked[0]!.entry.frontmatter.name).toBe('x');
+  });
+
+  it('an empty query matches every entry with score 1', () => {
+    const ranked = rankByKeywords([entry('a', 'd', 'b'), entry('c', 'e', 'f')], '   ', 5);
+    expect(ranked).toHaveLength(2);
+    expect(ranked.every((r) => r.score === 1)).toBe(true);
+  });
+
+  it('searches tags too', () => {
+    const e = entry('a', 'desc', 'body', { tags: ['kubernetes', 'infra'] });
+    const ranked = rankByKeywords([e], 'kubernetes', 5);
+    expect(ranked).toHaveLength(1);
+  });
+});
+
+describe('recallVector dimension-drift hardening', () => {
+  let tmp: string;
+  beforeEach(async () => {
+    tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-search-'));
+  });
+  afterEach(async () => {
+    await fs.rm(tmp, { recursive: true, force: true });
+  });
+
+  it('degrades (no crash) when a misbehaving embedder under-returns vectors — no-cache path', async () => {
+    const mutex: Mutex = createMutex();
+    // Asked for corpus.length + 1 vectors, returns only one — the query vector
+    // is absent. Must NOT throw a TypeError on `vec.length`/`query.length`.
+    const liar: EmbeddingProvider = {
+      name: 'liar',
+      dim: 2,
+      async embed() {
+        return [[1, 0]];
+      },
+    };
+    const all = [entry('a', 'da', 'ba'), entry('b', 'db', 'bb')];
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const ranked = await recallVector(all, 'q', 5, liar, null, mutex);
+      expect(Array.isArray(ranked)).toBe(true);
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('returns empty (no crash) when the embedder returns no vectors at all', async () => {
+    const mutex: Mutex = createMutex();
+    const empty: EmbeddingProvider = {
+      name: 'empty',
+      dim: 2,
+      async embed() {
+        return [];
+      },
+    };
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const ranked = await recallVector([entry('a', 'd', 'b')], 'q', 5, empty, null, mutex);
+      expect(ranked).toEqual([]);
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('does not poison the persistent cache with an undefined vector when the embedder under-returns', async () => {
+    const mutex: Mutex = createMutex();
+    const liar: EmbeddingProvider = {
+      name: 'liar',
+      dim: 2,
+      async embed() {
+        return [[1, 0]]; // misses=2 + query=1 requested; only 1 returned
+      },
+    };
+    const index = new EmbeddingIndex(tmp, 'liar', 2);
+    const all = [entry('a', 'da', 'ba'), entry('b', 'db', 'bb')];
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      await recallVector(all, 'q', 5, liar, index, mutex);
+    } finally {
+      warn.mockRestore();
+    }
+    // Whatever landed on disk must be well-formed: every cached vector is a real
+    // numeric array, never `null`/`undefined` (a poisoned cache breaks all recall).
+    const raw = await fs
+      .readFile(path.join(tmp, '.embeddings.json'), 'utf8')
+      .catch(() => '{"entries":{}}');
+    const parsed = JSON.parse(raw) as { entries?: Record<string, { vector?: unknown }> };
+    for (const e of Object.values(parsed.entries ?? {})) {
+      expect(Array.isArray(e.vector)).toBe(true);
+    }
+  });
+
+  it('skips a cached entry whose vector dim no longer matches the query (no silently-wrong score)', async () => {
+    const mutex: Mutex = createMutex();
+    // Pre-seed the persistent cache with a dim-3 vector for `stale`.
+    const seed = new EmbeddingIndex(tmp, 'drift');
+    const stale = entry('stale', 'stale desc', 'stale body');
+    const corpusText = ['stale', 'stale desc', '', 'stale body'].join('\n');
+    seed.set('stale', corpusText, [1, 0, 0]);
+    await seed.flush();
+
+    // An embedder that now returns dim-2 vectors (model/dim drift). The cached
+    // `stale` entry is dim-3; the fresh query is dim-2.
+    const driftEmbedder: EmbeddingProvider = {
+      name: 'drift',
+      dim: 2,
+      async embed(texts) {
+        return texts.map(() => [1, 0]);
+      },
+    };
+    const index = new EmbeddingIndex(tmp, 'drift'); // no dim → cache not invalidated on dim
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const ranked = await recallVector([stale], 'q', 5, driftEmbedder, index, mutex);
+      // The mismatched-dim entry is dropped, not ranked on a truncated basis.
+      expect(ranked).toHaveLength(0);
+      expect(warn).toHaveBeenCalled();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+});

package/src/store/search.ts

@@ -0,0 +1,197 @@
+import type { EmbeddingProvider, Mutex } from '@moxxy/sdk';
+import { TfIdfEmbedder, cosineSimilarity, tokenize } from '../tfidf.js';
+import type { EmbeddingIndex } from '../embedding-cache.js';
+import type { MemoryEntry } from './types.js';
+
+export interface RankedMemory {
+  readonly entry: MemoryEntry;
+  readonly score: number;
+}
+
+export async function recallVector(
+  all: ReadonlyArray<MemoryEntry>,
+  query: string,
+  limit: number,
+  embedder: EmbeddingProvider,
+  index: EmbeddingIndex | null,
+  mutex: Mutex,
+): Promise<ReadonlyArray<RankedMemory>> {
+  const corpus = all.map((e) => entryForEmbedding(e));
+
+  // TF-IDF special-cases the persistent cache (vocab is corpus-wide).
+  if (embedder instanceof TfIdfEmbedder) {
+    embedder.fit([...corpus, query]);
+    return rankAllFresh(all, corpus, query, limit, embedder);
+  }
+
+  // Neural embedders: consult the persistent cache, only embed misses + query.
+  if (index) {
+    // The index load->lookup->set->prune->flush cycle mutates the shared
+    // on-disk cache, so it must run under the store's write mutex — otherwise
+    // two concurrent recalls (or a recall racing forget()'s rebuildIndex)
+    // read the same snapshot and clobber each other's writes. Only the cache
+    // bookkeeping is serialized; the pure cosine ranking stays outside.
+    const { vectors, queryVec } = await mutex.run(async () => {
+      await index.load();
+      const cached: Array<ReadonlyArray<number> | null> = [];
+      const misses: { index: number; text: string }[] = [];
+      for (let i = 0; i < all.length; i++) {
+        const hit = index.lookup(all[i]!.frontmatter.name, corpus[i]!);
+        cached.push(hit);
+        if (!hit) misses.push({ index: i, text: corpus[i]! });
+      }
+      const queryIdx = misses.length;
+      const toEmbed = [...misses.map((m) => m.text), query];
+      const fresh = await embedder.embed(toEmbed);
+      const qVec = fresh[queryIdx];
+      // Map each missed corpus index to its freshly-embedded vector so the
+      // stitch loop below stays O(1) per entry instead of scanning `misses`.
+      // A misbehaving embedder may under-return; only valid vectors get mapped,
+      // and missing ones stay absent so rankCosine drops them (never crashes).
+      const freshByEntryIndex = new Map<number, ReadonlyArray<number>>();
+      for (const [j, m] of misses.entries()) {
+        const v = fresh[j];
+        if (Array.isArray(v)) freshByEntryIndex.set(m.index, v);
+      }
+      // Stitch results: cached + freshly-embedded. Holes (undefined) survive to
+      // rankCosine, which skips them rather than throwing.
+      const vecs: Array<ReadonlyArray<number> | undefined> = [];
+      for (let i = 0; i < all.length; i++) {
+        vecs.push(cached[i] ?? freshByEntryIndex.get(i));
+      }
+      // Persist ONLY valid fresh vectors — never write an `undefined`/non-array
+      // vector to the on-disk cache, which would poison it permanently (every
+      // future recall would read back a corrupt entry).
+      for (const [j, m] of misses.entries()) {
+        const v = fresh[j];
+        if (Array.isArray(v)) index.set(all[m.index]!.frontmatter.name, m.text, v);
+      }
+      index.prune(all.map((e) => e.frontmatter.name));
+      await index.flush();
+      return { vectors: vecs, queryVec: qVec };
+    });
+    return rankCosine(all, vectors, queryVec, limit);
+  }
+
+  // No cache configured — embed everything every time.
+  return rankAllFresh(all, corpus, query, limit, embedder);
+}
+
+// Embed `[...corpus, query]` in one batch, then cosine-rank the corpus against
+// the (last) query vector. Shared by the TF-IDF and no-cache branches.
+async function rankAllFresh(
+  all: ReadonlyArray<MemoryEntry>,
+  corpus: ReadonlyArray<string>,
+  query: string,
+  limit: number,
+  embedder: EmbeddingProvider,
+): Promise<ReadonlyArray<RankedMemory>> {
+  const vectors = await embedder.embed([...corpus, query]);
+  // The query is embedded at index `corpus.length`. Address it by that fixed
+  // position (not `vectors.length - 1`): if the embedder under-returns and drops
+  // the query, `length - 1` would silently grab the last CORPUS vector and use
+  // it as the query. `vectors[corpus.length]` is `undefined` in that case, which
+  // rankCosine handles by returning an empty result — degrade, never mislead.
+  const queryVec = vectors[corpus.length];
+  return rankCosine(all, vectors.slice(0, all.length), queryVec, limit);
+}
+
+export function rankByKeywords(
+  all: ReadonlyArray<MemoryEntry>,
+  query: string,
+  limit: number,
+): ReadonlyArray<RankedMemory> {
+  const tokens = tokenize(query);
+  return all
+    .map((entry) => ({ entry, score: scoreEntry(entry, tokens) }))
+    .filter((r) => r.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit);
+}
+
+function rankCosine(
+  entries: ReadonlyArray<MemoryEntry>,
+  vectors: ReadonlyArray<ReadonlyArray<number> | undefined>,
+  query: ReadonlyArray<number> | undefined,
+  limit: number,
+): ReadonlyArray<RankedMemory> {
+  // A misbehaving/hostile embedder can return fewer vectors than requested (or
+  // a non-array element) — the EmbeddingProvider.embed contract promises order
+  // but not count. Without this guard `query.length`/`vec.length` throws an
+  // opaque TypeError and recall crashes instead of degrading. A bad embedder
+  // must yield an empty/partial result set, never crash memory_recall.
+  if (!Array.isArray(query) || query.length === 0) {
+    console.warn(
+      '[plugin-memory] embedder returned no usable query vector; skipping vector recall',
+    );
+    return [];
+  }
+  const ranked: RankedMemory[] = [];
+  for (let i = 0; i < entries.length; i++) {
+    const vec = vectors[i];
+    // cosineSimilarity silently truncates to the shorter vector, so a stale
+    // cached vector or a provider quirk of the wrong dimensionality would
+    // produce a plausible-but-wrong score (invisible corruption). A missing
+    // vector (embedder under-returned) is the same hazard. Skip the entry
+    // loudly instead of ranking it on a mismatched or absent basis.
+    if (!Array.isArray(vec) || vec.length !== query.length) {
+      console.warn(
+        `[plugin-memory] skipping '${entries[i]!.frontmatter.name}' in recall: ` +
+          `vector dim ${Array.isArray(vec) ? vec.length : 'missing'} != query dim ${query.length} (cache/embedder drift)`,
+      );
+      continue;
+    }
+    const score = cosineSimilarity(vec, query);
+    if (score > 0) ranked.push({ entry: entries[i]!, score });
+  }
+  ranked.sort((a, b) => b.score - a.score);
+  return ranked.slice(0, limit);
+}
+
+// Count non-overlapping occurrences of `needle` in `haystack` without
+// allocating the intermediate array `haystack.split(needle)` would build.
+// Identical result to `split(needle).length - 1` for the non-empty tokens
+// `tokenize` yields. Tokens are `[a-z0-9_-]+`, so there are no overlap or
+// empty-needle edge cases to worry about.
+function countOccurrences(haystack: string, needle: string): number {
+  let n = 0;
+  let i = haystack.indexOf(needle);
+  while (i !== -1) {
+    n += 1;
+    i = haystack.indexOf(needle, i + needle.length);
+  }
+  return n;
+}
+
+function entryForEmbedding(entry: MemoryEntry): string {
+  return [
+    entry.frontmatter.name,
+    entry.frontmatter.description,
+    (entry.frontmatter.tags ?? []).join(' '),
+    entry.body,
+  ].join('\n');
+}
+
+function scoreEntry(entry: MemoryEntry, tokens: ReadonlyArray<string>): number {
+  if (tokens.length === 0) return 1;
+  const haystack = (
+    entry.frontmatter.name +
+    ' ' +
+    entry.frontmatter.description +
+    ' ' +
+    (entry.frontmatter.tags ?? []).join(' ') +
+    ' ' +
+    entry.body
+  ).toLowerCase();
+  let score = 0;
+  for (const t of tokens) {
+    if (!t) continue;
+    const matches = countOccurrences(haystack, t);
+    if (matches > 0) {
+      score += matches;
+      if (entry.frontmatter.name.toLowerCase().includes(t)) score += 3;
+      if (entry.frontmatter.description.toLowerCase().includes(t)) score += 2;
+    }
+  }
+  return score;
+}

package/src/store/types.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+
+export const memoryTypeSchema = z.enum(['fact', 'preference', 'project', 'reference']);
+export type MemoryType = z.infer<typeof memoryTypeSchema>;
+
+export const memoryFrontmatterSchema = z.object({
+  name: z.string().min(1).max(120).regex(/^[a-z0-9][a-z0-9-]*$/, 'name must be slug-like'),
+  type: memoryTypeSchema,
+  description: z.string().min(1).max(280),
+  tags: z.array(z.string().min(1)).optional(),
+  createdAt: z.string().optional(),
+  updatedAt: z.string().optional(),
+});
+
+export type MemoryFrontmatter = z.infer<typeof memoryFrontmatterSchema>;
+
+export interface MemoryEntry {
+  readonly frontmatter: MemoryFrontmatter;
+  readonly body: string;
+  readonly path: string;
+}
+
+export type RecallMode = 'auto' | 'vector' | 'keyword';

package/src/store.test.ts

@@ -0,0 +1,186 @@
+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 { MemoryStore } from './store.js';
+
+let tmp: string;
+const newStore = () => new MemoryStore({ dir: tmp });
+
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-mem-'));
+});
+afterEach(async () => {
+  await fs.rm(tmp, { recursive: true, force: true });
+});
+
+describe('MemoryStore', () => {
+  it('saves and round-trips an entry', async () => {
+    const store = newStore();
+    await store.save({ name: 'foo', type: 'fact', description: 'foo desc', body: 'foo body' });
+    const got = await store.get('foo');
+    expect(got?.frontmatter.name).toBe('foo');
+    expect(got?.frontmatter.type).toBe('fact');
+    expect(got?.body).toBe('foo body');
+  });
+
+  it('emits valid Markdown with frontmatter on disk', async () => {
+    const store = newStore();
+    await store.save({ name: 'foo', type: 'fact', description: 'desc', body: 'body' });
+    const raw = await fs.readFile(path.join(tmp, 'foo.md'), 'utf8');
+    expect(raw).toContain('---');
+    expect(raw).toContain('name: foo');
+    expect(raw).toContain('type: fact');
+    expect(raw).toMatch(/createdAt: .+/);
+  });
+
+  it('serializes concurrent saves so MEMORY.md keeps every entry', async () => {
+    const store = newStore();
+    // Without the per-instance mutex, each save's rebuildIndex can read the
+    // entry list before a sibling save has written its file, so a concurrent
+    // save's row is dropped from MEMORY.md (and the writes race the file).
+    await Promise.all([
+      store.save({ name: 'a', type: 'fact', description: 'A.', body: 'a' }),
+      store.save({ name: 'b', type: 'fact', description: 'B.', body: 'b' }),
+      store.save({ name: 'c', type: 'fact', description: 'C.', body: 'c' }),
+    ]);
+    const idx = await fs.readFile(path.join(tmp, 'MEMORY.md'), 'utf8');
+    expect(idx).toContain('[a](a.md)');
+    expect(idx).toContain('[b](b.md)');
+    expect(idx).toContain('[c](c.md)');
+    expect(await store.list()).toHaveLength(3);
+  });
+
+  it('rebuilds the MEMORY.md index after each save', async () => {
+    const store = newStore();
+    await store.save({ name: 'a', type: 'fact', description: 'A.', body: '...' });
+    await store.save({ name: 'b', type: 'preference', description: 'B.', body: '...' });
+    const idx = await fs.readFile(path.join(tmp, 'MEMORY.md'), 'utf8');
+    expect(idx).toContain('## fact');
+    expect(idx).toContain('## preference');
+    expect(idx).toContain('[a](a.md)');
+    expect(idx).toContain('[b](b.md)');
+  });
+
+  it('list filters by type', async () => {
+    const store = newStore();
+    await store.save({ name: 'a', type: 'fact', description: 'A', body: '.' });
+    await store.save({ name: 'b', type: 'preference', description: 'B', body: '.' });
+    const facts = await store.list('fact');
+    expect(facts).toHaveLength(1);
+    expect(facts[0]!.frontmatter.name).toBe('a');
+  });
+
+  it('update preserves createdAt but bumps updatedAt', async () => {
+    const store = newStore();
+    await store.save({ name: 'foo', type: 'fact', description: 'd', body: 'orig' });
+    const first = (await store.get('foo'))!;
+    await new Promise((r) => setTimeout(r, 10));
+    await store.update('foo', { body: 'updated' });
+    const second = (await store.get('foo'))!;
+    expect(second.frontmatter.createdAt).toBe(first.frontmatter.createdAt);
+    expect(second.frontmatter.updatedAt).not.toBe(first.frontmatter.updatedAt);
+    expect(second.body).toBe('updated');
+  });
+
+  it('forget deletes the file and updates the index', async () => {
+    const store = newStore();
+    await store.save({ name: 'a', type: 'fact', description: 'A', body: '.' });
+    expect(await store.forget('a')).toBe(true);
+    expect(await store.forget('a')).toBe(false);
+    const idx = await fs.readFile(path.join(tmp, 'MEMORY.md'), 'utf8').catch(() => '');
+    expect(idx).not.toContain('[a]');
+  });
+
+  it('returns empty list when dir does not exist', async () => {
+    const store = new MemoryStore({ dir: path.join(tmp, 'nope') });
+    expect(await store.list()).toEqual([]);
+  });
+
+  it('recall ranks by token frequency + name/description matches', async () => {
+    const store = newStore();
+    await store.save({
+      name: 'team-likes-trpc',
+      type: 'preference',
+      description: 'The team prefers tRPC over REST.',
+      body: 'When generating new endpoints, scaffold a tRPC router.',
+    });
+    await store.save({
+      name: 'prod-postgres',
+      type: 'project',
+      description: 'Production runs Postgres 16.',
+      body: 'All migrations target Postgres 16. Use `pg_dump` for backups.',
+    });
+    const matches = await store.recall('trpc endpoints');
+    expect(matches[0]!.entry.frontmatter.name).toBe('team-likes-trpc');
+    const pg = await store.recall('postgres');
+    expect(pg[0]!.entry.frontmatter.name).toBe('prod-postgres');
+  });
+
+  it('rejects invalid frontmatter at save time via the schema', async () => {
+    const store = newStore();
+    await expect(
+      store.save({ name: 'Bad Name', type: 'fact', description: 'd', body: '.' } as never),
+    ).rejects.toThrow();
+  });
+
+  it('maintains the index incrementally — a save does not re-read every memory file', async () => {
+    const store = newStore();
+    // First save hydrates the row cache from disk (one readdir + reads).
+    await store.save({ name: 'a', type: 'fact', description: 'A', body: 'a' });
+    const readdirSpy = vi.spyOn(fs, 'readdir');
+    const readFileSpy = vi.spyOn(fs, 'readFile');
+    try {
+      await store.save({ name: 'b', type: 'fact', description: 'B', body: 'b' });
+      await store.save({ name: 'c', type: 'preference', description: 'C', body: 'c' });
+      // No directory re-scan; the only reads are each entry's own
+      // read-modify-write (createdAt preservation), not a full re-index.
+      expect(readdirSpy).not.toHaveBeenCalled();
+      expect(readFileSpy.mock.calls.length).toBeLessThanOrEqual(2);
+    } finally {
+      readdirSpy.mockRestore();
+      readFileSpy.mockRestore();
+    }
+    const idx = await fs.readFile(path.join(tmp, 'MEMORY.md'), 'utf8');
+    expect(idx).toContain('[a](a.md)');
+    expect(idx).toContain('[b](b.md)');
+    expect(idx).toContain('[c](c.md)');
+  });
+
+  it('incremental index survives forget and a fresh store rehydrates from disk', async () => {
+    const store = newStore();
+    await store.save({ name: 'a', type: 'fact', description: 'A', body: 'a' });
+    await store.save({ name: 'b', type: 'fact', description: 'B', body: 'b' });
+    await store.forget('a');
+    const idx = await fs.readFile(path.join(tmp, 'MEMORY.md'), 'utf8');
+    expect(idx).not.toContain('[a](a.md)');
+    expect(idx).toContain('[b](b.md)');
+    // A new instance (cold cache) sees the same state.
+    const fresh = newStore();
+    await fresh.save({ name: 'c', type: 'fact', description: 'C', body: 'c' });
+    const idx2 = await fs.readFile(path.join(tmp, 'MEMORY.md'), 'utf8');
+    expect(idx2).not.toContain('[a](a.md)');
+    expect(idx2).toContain('[b](b.md)');
+    expect(idx2).toContain('[c](c.md)');
+  });
+
+  it('soft cap is warn-only: saves past maxMemories succeed, capStatus flips, nothing evicted', async () => {
+    const store = new MemoryStore({ dir: tmp, maxMemories: 2 });
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      await store.save({ name: 'a', type: 'fact', description: 'A', body: 'a' });
+      await store.save({ name: 'b', type: 'fact', description: 'B', body: 'b' });
+      expect((await store.capStatus()).over).toBe(false);
+      expect(warn).not.toHaveBeenCalled();
+
+      await store.save({ name: 'c', type: 'fact', description: 'C', body: 'c' });
+      const cap = await store.capStatus();
+      expect(cap).toEqual({ count: 3, max: 2, over: true });
+      expect(warn).toHaveBeenCalledOnce();
+      // Warn-only: every entry is still on disk and listed.
+      expect((await store.list()).map((e) => e.frontmatter.name).sort()).toEqual(['a', 'b', 'c']);
+    } finally {
+      warn.mockRestore();
+    }
+  });
+});