@moxxy/plugin-memory 0.27.0

package/src/index.ts

@@ -0,0 +1,247 @@
+import { defineTool, defineEmbedder, definePlugin, z, type Plugin } from '@moxxy/sdk';
+import { MemoryStore, memoryTypeSchema, type MemoryStoreOptions } from './store.js';
+import { TfIdfEmbedder } from './tfidf.js';
+
+export {
+  MemoryStore,
+  memoryTypeSchema,
+  memoryFrontmatterSchema,
+  defaultMemoryDir,
+  type MemoryEntry,
+  type MemoryFrontmatter,
+  type MemoryStoreOptions,
+  type MemoryType,
+  type RankedMemory,
+  type RecallMode,
+} from './store.js';
+export { parseMdFile, parseFrontmatter, renderFrontmatter } from './parse.js';
+export { recentExchanges, summarizeSession, type SessionFact } from './stm.js';
+export { TfIdfEmbedder, cosineSimilarity, tokenize } from './tfidf.js';
+export { EmbeddingIndex } from './embedding-cache.js';
+export {
+  planConsolidation,
+  consolidateMemory,
+  buildMemoryConsolidatePlugin,
+  memoryConsolidatePlugin,
+  type ConsolidatePlan,
+  type ConsolidateOptions,
+  type ConsolidationOutcome,
+} from './consolidate.js';
+import { memoryConsolidatePlugin as memoryConsolidatePluginRef } from './consolidate.js';
+
+export interface BuildMemoryPluginOptions extends MemoryStoreOptions {}
+
+export function buildMemoryPlugin(opts: BuildMemoryPluginOptions = {}): { plugin: Plugin; store: MemoryStore } {
+  const store = new MemoryStore(opts);
+  const plugin = definePlugin({
+    name: '@moxxy/plugin-memory',
+    version: '0.0.0',
+    // Publish the long-term store on the inter-plugin service registry so the
+    // sibling @moxxy/memory-consolidate plugin can resolve it in its own onInit
+    // instead of being hand-built with the store — the seam that lets both be
+    // discovery-loaded. memory-consolidate is registered after this plugin, so
+    // this onInit runs first.
+    hooks: {
+      onInit: (ctx) => {
+        ctx.services.register('memory', store);
+      },
+    },
+    // The zero-dep TF-IDF embedder, contributed as a selectable embedder so it
+    // sits in the same registry as openai/transformers/custom ones.
+    embedders: [
+      defineEmbedder({
+        name: 'tfidf',
+        displayName: 'TF-IDF (built-in, zero-dep)',
+        createClient: () => new TfIdfEmbedder(),
+      }),
+    ],
+    tools: [
+      defineTool({
+        name: 'memory_save',
+        description:
+          'Persist a memory to long-term storage. Use sparingly — only for facts/preferences/' +
+          'project context that would help you in future sessions. Keep the body terse.',
+        inputSchema: z.object({
+          name: z.string().min(1).regex(/^[a-z0-9][a-z0-9-]*$/, 'name must be slug-like'),
+          type: memoryTypeSchema,
+          description: z.string().min(1).max(280),
+          body: z.string().min(1).max(4000),
+          tags: z.array(z.string().min(1)).optional(),
+        }),
+        permission: { action: 'prompt' },
+        isolation: {
+          capabilities: {
+            fs: { read: ['~/.moxxy/memory/**'], write: ['~/.moxxy/memory/**'] },
+            net: { mode: 'none' },
+            timeMs: 5_000,
+          },
+        },
+        handler: async ({ name, type, description, body, tags }) => {
+          const saved = await store.save({ name, type, description, body, tags });
+          const cap = await store.capStatus();
+          return {
+            name: saved.frontmatter.name,
+            path: saved.path,
+            // Warn-only soft cap: the save succeeded, but tell the model the
+            // store is overgrown so it consolidates / forgets stale entries.
+            ...(cap.over
+              ? {
+                  warning:
+                    `memory store holds ${cap.count} entries (soft cap ${cap.max}). ` +
+                    `Nothing was evicted — consider consolidating related memories or using memory_forget on stale ones.`,
+                }
+              : {}),
+          };
+        },
+      }),
+      defineTool({
+        name: 'memory_recall',
+        description:
+          'Search long-term memory by free-text query. Uses vector similarity (TF-IDF by default, ' +
+          'or a configured EmbeddingProvider) when mode is "auto" or "vector". Returns the most ' +
+          'relevant entries with their full bodies.',
+        inputSchema: z.object({
+          query: z.string().min(1),
+          limit: z.number().int().min(1).max(20).optional().default(5),
+          type: memoryTypeSchema.optional(),
+          mode: z.enum(['auto', 'vector', 'keyword']).optional().default('auto'),
+        }),
+        isolation: {
+          capabilities: {
+            fs: { read: ['~/.moxxy/memory/**'] },
+            // Vector recall may call out to an EmbeddingProvider (OpenAI,
+            // local transformers, …). The inproc isolator can't enforce
+            // this; a stronger isolator should constrain to the actual
+            // configured embedder's host.
+            net: { mode: 'any' },
+            timeMs: 15_000,
+          },
+        },
+        handler: async ({ query, limit, type, mode }) => {
+          const matches = await store.recall(query, { limit, type, mode });
+          return matches.map(({ entry, score }) => ({
+            name: entry.frontmatter.name,
+            type: entry.frontmatter.type,
+            description: entry.frontmatter.description,
+            body: entry.body,
+            score,
+          }));
+        },
+      }),
+      defineTool({
+        name: 'memory_list',
+        description: 'List all stored memories (name + type + description, no body).',
+        inputSchema: z.object({ type: memoryTypeSchema.optional() }),
+        isolation: {
+          capabilities: {
+            fs: { read: ['~/.moxxy/memory/**'] },
+            net: { mode: 'none' },
+            timeMs: 5_000,
+          },
+        },
+        handler: async ({ type }) => {
+          const entries = await store.list(type);
+          return entries.map((e) => ({
+            name: e.frontmatter.name,
+            type: e.frontmatter.type,
+            description: e.frontmatter.description,
+            tags: e.frontmatter.tags ?? [],
+          }));
+        },
+      }),
+      defineTool({
+        name: 'memory_forget',
+        description: 'Delete a memory by name. Use only when the memory is incorrect or no longer relevant.',
+        // Slug-only name: the inproc isolator does NOT enforce the fs.write glob,
+        // so this Zod guard is the sole defense against a path-traversal `name`
+        // (e.g. '../../vault') reaching fs.unlink. Mirror memory_save's regex.
+        inputSchema: z.object({
+          name: z.string().min(1).max(120).regex(/^[a-z0-9][a-z0-9-]*$/, 'name must be slug-like'),
+        }),
+        permission: { action: 'prompt' },
+        isolation: {
+          capabilities: {
+            fs: { read: ['~/.moxxy/memory/**'], write: ['~/.moxxy/memory/**'] },
+            net: { mode: 'none' },
+            timeMs: 5_000,
+          },
+        },
+        handler: async ({ name }) => {
+          const removed = await store.forget(name);
+          return removed ? `forgot ${name}` : `not found: ${name}`;
+        },
+      }),
+      defineTool({
+        name: 'memory_update',
+        description: 'Update an existing memory in place. createdAt is preserved; updatedAt bumps.',
+        inputSchema: z.object({
+          // Slug-only: see memory_forget — the schema is the only traversal guard.
+          name: z.string().min(1).max(120).regex(/^[a-z0-9][a-z0-9-]*$/, 'name must be slug-like'),
+          description: z.string().min(1).max(280).optional(),
+          body: z.string().min(1).max(4000).optional(),
+          tags: z.array(z.string().min(1)).optional(),
+        }),
+        permission: { action: 'prompt' },
+        isolation: {
+          capabilities: {
+            fs: { read: ['~/.moxxy/memory/**'], write: ['~/.moxxy/memory/**'] },
+            net: { mode: 'none' },
+            timeMs: 5_000,
+          },
+        },
+        handler: async ({ name, description, body, tags }) => {
+          const updated = await store.update(name, { description, body, tags });
+          if (!updated) throw new Error(`memory '${name}' not found`);
+          return { name: updated.frontmatter.name, updatedAt: updated.frontmatter.updatedAt };
+        },
+      }),
+    ],
+  });
+  return { plugin, store };
+}
+
+
+/**
+ * Discovery-loadable instance: the WHOLE memory feature (long-term store +
+ * memory_save/recall/… tools + the tfidf embedder + memory_consolidate and
+ * its nudge hooks) as ONE plugin, so the package unbundles cleanly — the
+ * loader takes a single default export per package. Composition over the
+ * existing builders:
+ *  - the store's embedder resolves LAZILY from the host-published
+ *    'embedders' registry service (captured in onInit, read on first
+ *    recall), replacing the bootstrap closure the CLI used to inject;
+ *  - our onInit registers the 'memory' service FIRST, then runs
+ *    consolidate's onInit, which resolves it — same ordering the two
+ *    separate builtin entries relied on.
+ * `buildMemoryPlugin` stays for hosts/tests that inject their own store.
+ */
+export const memoryPlugin: Plugin = (() => {
+  let embeddersReg: { tryGetActive(): unknown } | null = null;
+  const { plugin: base } = buildMemoryPlugin({
+    // The registry hands back an EmbedderClient-compatible instance; the
+    // structural cast keeps this file free of a core import.
+    embedder: () =>
+      (embeddersReg?.tryGetActive() ?? null) as ReturnType<
+        Extract<NonNullable<MemoryStoreOptions['embedder']>, () => unknown>
+      >,
+  });
+  const consolidate = memoryConsolidatePluginRef;
+  return definePlugin({
+    name: '@moxxy/plugin-memory',
+    version: '0.0.0',
+    ...(base.embedders ? { embedders: base.embedders } : {}),
+    tools: [...(base.tools ?? []), ...(consolidate.tools ?? [])],
+    hooks: {
+      ...consolidate.hooks,
+      onInit: async (ctx) => {
+        embeddersReg =
+          ctx.services.get<{ tryGetActive(): unknown }>('embedders') ?? null;
+        await base.hooks?.onInit?.(ctx);
+        await consolidate.hooks?.onInit?.(ctx);
+      },
+    },
+  });
+})();
+
+// Discovery entry: `createPluginLoader` requires a default Plugin export.
+export default memoryPlugin;

package/src/parse.ts

@@ -0,0 +1,12 @@
+// The MD+frontmatter parser now lives canonically in @moxxy/sdk
+// (`parseFrontmatterFile`/`parseFrontmatter`/`renderFrontmatter`), shared with
+// @moxxy/core so the previously-copy-pasted copies can't diverge. This module
+// keeps the historical `parseMdFile`/`ParsedFile` names as thin re-exports.
+// (The plugin already depends on @moxxy/sdk, so this stays leaf-only.)
+import { parseFrontmatterFile, type ParsedFrontmatter } from '@moxxy/sdk';
+
+export type ParsedFile = ParsedFrontmatter;
+
+export const parseMdFile = parseFrontmatterFile;
+
+export { parseFrontmatter, renderFrontmatter } from '@moxxy/sdk';

package/src/stm.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { asPluginId, asSessionId, asToolCallId, asTurnId, type MoxxyEvent } from '@moxxy/sdk';
+import { recentExchanges, summarizeSession } from './stm.js';
+
+const sid = asSessionId('s');
+const tid = asTurnId('t');
+const c1 = asToolCallId('c1');
+const p1 = asPluginId('p1');
+
+const stubLog = (events: MoxxyEvent[]) => ({
+  length: events.length,
+  at: (n: number) => events[n],
+  slice: () => events.slice(),
+  ofType: <T extends MoxxyEvent['type']>(type: T) =>
+    events.filter((e): e is Extract<MoxxyEvent, { type: T }> => e.type === type),
+  byTurn: () => events.slice(),
+  toJSON: () => events.slice(),
+});
+
+const ev = (e: Partial<MoxxyEvent> & Pick<MoxxyEvent, 'type'>, seq: number): MoxxyEvent =>
+  ({
+    sessionId: sid,
+    turnId: tid,
+    source: 'system',
+    id: `e${seq}` as never,
+    seq,
+    ts: 0,
+    ...e,
+  }) as MoxxyEvent;
+
+describe('recentExchanges', () => {
+  it('returns the most recent N user+assistant messages', () => {
+    const log = stubLog([
+      ev({ type: 'user_prompt', text: 'hi', source: 'user' }, 0),
+      ev({ type: 'assistant_message', content: 'hello', stopReason: 'end_turn', source: 'model' }, 1),
+      ev({ type: 'user_prompt', text: 'next', source: 'user' }, 2),
+    ]);
+    const recent = recentExchanges(log, 2);
+    expect(recent.map((r) => r.source)).toEqual(['assistant', 'user']);
+    expect(recent[1]!.text).toBe('next');
+  });
+
+  it('ignores non-message events', () => {
+    const log = stubLog([
+      ev({ type: 'user_prompt', text: 'a', source: 'user' }, 0),
+      ev({ type: 'tool_call_requested', callId: c1, name: 'X', input: {}, source: 'model' }, 1),
+      ev({ type: 'assistant_message', content: 'done', stopReason: 'end_turn', source: 'model' }, 2),
+    ]);
+    expect(recentExchanges(log).map((r) => r.source)).toEqual(['user', 'assistant']);
+  });
+});
+
+describe('summarizeSession', () => {
+  it('counts turns, tool calls, errors, skills, plugins', () => {
+    const log = stubLog([
+      ev({ type: 'user_prompt', text: '', source: 'user' }, 0),
+      ev({ type: 'tool_call_requested', callId: c1, name: 'X', input: {}, source: 'model' }, 1),
+      ev({ type: 'error', kind: 'fatal', message: '!', source: 'system' }, 2),
+      ev({ type: 'plugin_registered', pluginId: p1, name: 'p', version: '1', kind: ['tools'], source: 'system' }, 3),
+    ]);
+    expect(summarizeSession(log)).toEqual({
+      turns: 1,
+      toolCalls: 1,
+      errors: 1,
+      skillsCreated: 0,
+      pluginsLoaded: 1,
+    });
+  });
+});

package/src/stm.ts

@@ -0,0 +1,48 @@
+import type { EventLogReader } from '@moxxy/sdk';
+
+export interface SessionFact {
+  readonly turnId: string;
+  readonly seq: number;
+  readonly source: 'user' | 'assistant';
+  readonly text: string;
+}
+
+/**
+ * Short-term memory helpers. STM is the event log itself — these selectors
+ * just project a useful view over it.
+ */
+
+export function recentExchanges(log: EventLogReader, n = 5): ReadonlyArray<SessionFact> {
+  const out: SessionFact[] = [];
+  for (const e of log.slice()) {
+    if (e.type === 'user_prompt') {
+      out.push({ turnId: e.turnId, seq: e.seq, source: 'user', text: e.text });
+    } else if (e.type === 'assistant_message') {
+      out.push({ turnId: e.turnId, seq: e.seq, source: 'assistant', text: e.content });
+    }
+  }
+  return out.slice(-n);
+}
+
+export function summarizeSession(log: EventLogReader): {
+  turns: number;
+  toolCalls: number;
+  errors: number;
+  skillsCreated: number;
+  pluginsLoaded: number;
+} {
+  const seenTurns = new Set<string>();
+  let toolCalls = 0;
+  let errors = 0;
+  let skillsCreated = 0;
+  let pluginsLoaded = 0;
+  for (const e of log.slice()) {
+    seenTurns.add(e.turnId);
+    if (e.type === 'tool_call_requested') toolCalls += 1;
+    if (e.type === 'error') errors += 1;
+    if (e.type === 'skill_created') skillsCreated += 1;
+    if (e.type === 'plugin_registered') pluginsLoaded += 1;
+    if (e.type === 'plugin_unregistered') pluginsLoaded -= 1;
+  }
+  return { turns: seenTurns.size, toolCalls, errors, skillsCreated, pluginsLoaded };
+}

package/src/store/io.test.ts

@@ -0,0 +1,100 @@
+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 { listEntries, readEntry, safeRead } from './io.js';
+
+let tmp: string;
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-io-'));
+});
+afterEach(async () => {
+  await fs.rm(tmp, { recursive: true, force: true });
+});
+
+async function writeEntry(name: string, type = 'fact'): Promise<void> {
+  const md =
+    `---\nname: ${name}\ntype: ${type}\ndescription: ${name} desc\n` +
+    `createdAt: 2026-01-01T00:00:00Z\nupdatedAt: 2026-01-01T00:00:00Z\n---\n\nbody ${name}\n`;
+  await fs.writeFile(path.join(tmp, `${name}.md`), md);
+}
+
+describe('listEntries', () => {
+  it('returns [] for a missing directory', async () => {
+    expect(await listEntries(path.join(tmp, 'nope'))).toEqual([]);
+  });
+
+  it('parses all .md entries, skipping MEMORY.md and non-md files', async () => {
+    await writeEntry('a');
+    await writeEntry('b');
+    await fs.writeFile(path.join(tmp, 'MEMORY.md'), '# index');
+    await fs.writeFile(path.join(tmp, 'notes.txt'), 'ignore me');
+    const entries = await listEntries(tmp);
+    expect(entries.map((e) => e.frontmatter.name).sort()).toEqual(['a', 'b']);
+  });
+
+  it('honors the type filter', async () => {
+    await writeEntry('a', 'fact');
+    await writeEntry('b', 'preference');
+    const facts = await listEntries(tmp, 'fact');
+    expect(facts.map((e) => e.frontmatter.name)).toEqual(['a']);
+  });
+
+  it('drops files whose frontmatter fails validation (no throw)', async () => {
+    await writeEntry('good');
+    await fs.writeFile(path.join(tmp, 'bad.md'), '---\nname: bad\n---\nno type\n');
+    const entries = await listEntries(tmp);
+    expect(entries.map((e) => e.frontmatter.name)).toEqual(['good']);
+  });
+
+  it('reads entry files concurrently rather than serially', async () => {
+    for (let i = 0; i < 6; i++) await writeEntry(`e${i}`);
+
+    let inFlight = 0;
+    let maxInFlight = 0;
+    const realRead = fs.readFile.bind(fs);
+    const spy = vi
+      .spyOn(fs, 'readFile')
+      // @ts-expect-error — match the (path, enc) overload we use
+      .mockImplementation(async (p: Parameters<typeof realRead>[0], enc) => {
+        inFlight++;
+        maxInFlight = Math.max(maxInFlight, inFlight);
+        await new Promise((r) => setTimeout(r, 10));
+        try {
+          // @ts-expect-error — forward to the real implementation
+          return await realRead(p, enc);
+        } finally {
+          inFlight--;
+        }
+      });
+
+    const entries = await listEntries(tmp);
+    spy.mockRestore();
+
+    // Correctness preserved.
+    expect(entries.map((e) => e.frontmatter.name).sort()).toEqual([
+      'e0',
+      'e1',
+      'e2',
+      'e3',
+      'e4',
+      'e5',
+    ]);
+    // If reads were serialized (await-in-loop) maxInFlight would be 1.
+    expect(maxInFlight).toBeGreaterThan(1);
+  });
+});
+
+describe('safeRead', () => {
+  it('agrees with readEntry on the body (both trim surrounding whitespace)', async () => {
+    const md =
+      `---\nname: x\ntype: fact\ndescription: x desc\n` +
+      `createdAt: 2026-01-01T00:00:00Z\nupdatedAt: 2026-01-01T00:00:00Z\n---\n\n\n  padded body  \n\n`;
+    const file = path.join(tmp, 'x.md');
+    await fs.writeFile(file, md);
+    const viaSafe = await safeRead(file);
+    const viaEntry = await readEntry(file);
+    expect(viaSafe?.body).toBe('padded body');
+    expect(viaSafe?.body).toBe(viaEntry?.body);
+  });
+});

package/src/store/io.ts

@@ -0,0 +1,138 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { writeFileAtomic } from '@moxxy/sdk/server';
+import { parseMdFile } from '../parse.js';
+import {
+  memoryFrontmatterSchema,
+  type MemoryEntry,
+  type MemoryFrontmatter,
+  type MemoryType,
+} from './types.js';
+
+export async function safeRead(
+  filePath: string,
+): Promise<{ frontmatter: MemoryFrontmatter; body: string } | null> {
+  try {
+    const raw = await fs.readFile(filePath, 'utf8');
+    const parsed = parseMdFile(raw);
+    const result = memoryFrontmatterSchema.safeParse(parsed.frontmatter);
+    if (!result.success) return null;
+    // Trim the body so safeRead agrees with readEntry/listEntries on the same
+    // file — they both `.trim()`. safeRead's only caller (writeEntry) reads just
+    // createdAt and discards the body, so this is behavior-preserving today; it
+    // removes the latent trap where a future body consumer would see different
+    // whitespace depending on which read path it used.
+    return { frontmatter: result.data, body: parsed.body.trim() };
+  } catch {
+    return null;
+  }
+}
+
+export function isEnoent(err: unknown): boolean {
+  return err instanceof Error && 'code' in err && (err as NodeJS.ErrnoException).code === 'ENOENT';
+}
+
+/**
+ * Cap on simultaneously-open file descriptors when reading a memory dir. The
+ * soft cap on entry count is warn-only, so a long-lived dir can hold thousands
+ * of files; an unbounded `Promise.all(readFile)` over all of them would open
+ * thousands of fds at once and can hit the OS limit (EMFILE) — failing every
+ * list/recall. Batching keeps the common case fast but bounds fd pressure.
+ */
+const READ_CONCURRENCY = 32;
+
+export async function listEntries(
+  dir: string,
+  filterType?: MemoryType,
+): Promise<ReadonlyArray<MemoryEntry>> {
+  let names: import('node:fs').Dirent[];
+  try {
+    names = await fs.readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (isEnoent(err)) return [];
+    throw err;
+  }
+  // recall() and rows() both call this on the hot path; with up to
+  // DEFAULT_MAX_MEMORIES (500) entries, reading+parsing each file serially is
+  // 500 strictly-ordered disk round-trips. The reads are independent, so fan
+  // them out concurrently (bounded by READ_CONCURRENCY) and preserve dirent
+  // order in the result.
+  const candidates = names.filter(
+    (d) => d.isFile() && d.name.endsWith('.md') && d.name !== 'MEMORY.md',
+  );
+  const readOne = async (dirent: import('node:fs').Dirent): Promise<MemoryEntry | null> => {
+    const filePath = path.join(dir, dirent.name);
+    let raw: string;
+    try {
+      raw = await fs.readFile(filePath, 'utf8');
+    } catch (err) {
+      // One unreadable file (deleted between readdir and readFile, transient
+      // permission error) must not fail the whole list. Drop it, surface
+      // non-ENOENT causes for diagnosis.
+      if (!isEnoent(err)) {
+        console.warn(`[plugin-memory] skipping unreadable memory file ${filePath}: ${String(err)}`);
+      }
+      return null;
+    }
+    const md = parseMdFile(raw);
+    const result = memoryFrontmatterSchema.safeParse(md.frontmatter);
+    if (!result.success) {
+      // A malformed entry silently vanishing from recall/index is a data-loss
+      // surprise; leave a breadcrumb so it's diagnosable.
+      console.warn(`[plugin-memory] ignoring memory file with invalid frontmatter: ${filePath}`);
+      return null;
+    }
+    if (filterType && result.data.type !== filterType) return null;
+    return {
+      frontmatter: result.data,
+      body: md.body.trim(),
+      path: filePath,
+    } satisfies MemoryEntry;
+  };
+  const parsed: Array<MemoryEntry | null> = [];
+  for (let i = 0; i < candidates.length; i += READ_CONCURRENCY) {
+    const batch = candidates.slice(i, i + READ_CONCURRENCY);
+    parsed.push(...(await Promise.all(batch.map(readOne))));
+  }
+  return parsed.filter((e): e is MemoryEntry => e !== null);
+}
+
+export async function readEntry(filePath: string): Promise<MemoryEntry | null> {
+  try {
+    const raw = await fs.readFile(filePath, 'utf8');
+    const parsed = parseMdFile(raw);
+    const result = memoryFrontmatterSchema.safeParse(parsed.frontmatter);
+    if (!result.success) return null;
+    return { frontmatter: result.data, body: parsed.body.trim(), path: filePath };
+  } catch (err) {
+    if (isEnoent(err)) return null;
+    throw err;
+  }
+}
+
+/** What the MEMORY.md index needs per entry — no body, so the incremental
+ *  index cache in MemoryStore can feed it without re-reading entry files. */
+export type IndexRow = Pick<MemoryEntry, 'frontmatter' | 'path'>;
+
+export async function writeIndex(
+  dir: string,
+  entries: ReadonlyArray<IndexRow>,
+): Promise<void> {
+  const lines = ['# Memory index', ''];
+  const byType = new Map<MemoryType, IndexRow[]>();
+  for (const e of entries) {
+    const list = byType.get(e.frontmatter.type) ?? [];
+    list.push(e);
+    byType.set(e.frontmatter.type, list);
+  }
+  for (const t of ['fact', 'preference', 'project', 'reference'] as const) {
+    const items = byType.get(t);
+    if (!items || items.length === 0) continue;
+    lines.push(`## ${t}`);
+    for (const item of items) {
+      lines.push(`- [${item.frontmatter.name}](${path.basename(item.path)}) — ${item.frontmatter.description}`);
+    }
+    lines.push('');
+  }
+  await writeFileAtomic(path.join(dir, 'MEMORY.md'), lines.join('\n'));
+}