lyra-core 0.1.0

package/src/mcp/stdio-client.ts

@@ -0,0 +1,154 @@
+import { type ChildProcess, spawn } from 'node:child_process'
+import type { McpServerStdio } from './types'
+
+interface JsonRpcRequest {
+  jsonrpc: '2.0'
+  id: number
+  method: string
+  params?: unknown
+}
+
+interface JsonRpcResponse {
+  jsonrpc: '2.0'
+  id: number
+  result?: unknown
+  error?: { code: number; message: string; data?: unknown }
+}
+
+interface JsonRpcNotification {
+  jsonrpc: '2.0'
+  method: string
+  params?: unknown
+}
+
+type JsonRpcMessage = JsonRpcResponse | JsonRpcNotification
+
+const PROTOCOL_VERSION = '2024-11-05'
+const CLIENT_INFO = { name: 'lyra', version: '0.8.1' }
+
+export class McpStdioClient {
+  private proc: ChildProcess | null = null
+  private nextId = 1
+  private buffer = ''
+  private readonly pending = new Map<
+    number,
+    { resolve: (v: unknown) => void; reject: (e: Error) => void }
+  >()
+  private starting: Promise<void> | null = null
+
+  constructor(public readonly server: McpServerStdio) {}
+
+  async ensureStarted(timeoutMs = 10_000): Promise<void> {
+    if (this.proc) return
+    if (this.starting) return this.starting
+    this.starting = this.spawnAndInitialize(timeoutMs)
+    try {
+      await this.starting
+    } finally {
+      this.starting = null
+    }
+  }
+
+  private async spawnAndInitialize(timeoutMs: number): Promise<void> {
+    const proc = spawn(this.server.command, this.server.args ?? [], {
+      env: { ...process.env, ...(this.server.env ?? {}) },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    this.proc = proc
+    proc.stdout?.setEncoding('utf8')
+    proc.stdout?.on('data', chunk => this.onStdout(chunk as string))
+    proc.on('error', err => this.failAll(err))
+    proc.on('exit', () => this.failAll(new Error(`mcp server '${this.server.name}' exited`)))
+    // Initialize handshake
+    const initPromise = this.request('initialize', {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: CLIENT_INFO,
+    })
+    const timeout = new Promise<never>((_, reject) =>
+      setTimeout(() => reject(new Error(`mcp init timeout (${timeoutMs}ms)`)), timeoutMs),
+    )
+    await Promise.race([initPromise, timeout])
+    this.notify('notifications/initialized', {})
+  }
+
+  async listTools(): Promise<{ name: string; description?: string; inputSchema?: unknown }[]> {
+    await this.ensureStarted()
+    const result = (await this.request('tools/list', {})) as {
+      tools?: { name: string; description?: string; inputSchema?: unknown }[]
+    }
+    return result.tools ?? []
+  }
+
+  async callTool(name: string, args: unknown): Promise<unknown> {
+    await this.ensureStarted()
+    return await this.request('tools/call', { name, arguments: args })
+  }
+
+  request(method: string, params: unknown): Promise<unknown> {
+    if (!this.proc?.stdin) throw new Error('mcp server not started')
+    const id = this.nextId++
+    const req: JsonRpcRequest = { jsonrpc: '2.0', id, method, params }
+    return new Promise<unknown>((resolve, reject) => {
+      this.pending.set(id, { resolve, reject })
+      this.proc!.stdin!.write(`${JSON.stringify(req)}\n`, err => {
+        if (err) {
+          this.pending.delete(id)
+          reject(err)
+        }
+      })
+    })
+  }
+
+  notify(method: string, params: unknown): void {
+    if (!this.proc?.stdin) return
+    const note: JsonRpcNotification = { jsonrpc: '2.0', method, params }
+    this.proc.stdin.write(`${JSON.stringify(note)}\n`)
+  }
+
+  close(): void {
+    if (!this.proc) return
+    try {
+      this.proc.stdin?.end()
+    } catch {}
+    try {
+      this.proc.kill('SIGTERM')
+    } catch {}
+    this.proc = null
+    this.failAll(new Error('mcp client closed'))
+  }
+
+  private onStdout(chunk: string): void {
+    this.buffer += chunk
+    let nl = this.buffer.indexOf('\n')
+    while (nl !== -1) {
+      const line = this.buffer.slice(0, nl).trim()
+      this.buffer = this.buffer.slice(nl + 1)
+      nl = this.buffer.indexOf('\n')
+      if (!line) continue
+      let parsed: JsonRpcMessage
+      try {
+        parsed = JSON.parse(line) as JsonRpcMessage
+      } catch {
+        continue
+      }
+      this.dispatch(parsed)
+    }
+  }
+
+  private dispatch(msg: JsonRpcMessage): void {
+    if ('id' in msg) {
+      const pending = this.pending.get(msg.id)
+      if (!pending) return
+      this.pending.delete(msg.id)
+      if (msg.error) pending.reject(new Error(`${msg.error.code}: ${msg.error.message}`))
+      else pending.resolve(msg.result ?? null)
+    }
+    // Notifications from the server are ignored for now.
+  }
+
+  private failAll(err: Error): void {
+    for (const { reject } of this.pending.values()) reject(err)
+    this.pending.clear()
+  }
+}

package/src/mcp/types.ts

@@ -0,0 +1,44 @@
+/**
+ * MCP server config shape (compatible with Claude Code's `.mcp.json`).
+ *
+ * stdio: `{ command, args?, env? }`. lyra spawns a subprocess and speaks
+ * JSON-RPC over its stdin/stdout.
+ *
+ * http: `{ type: 'http', url, headers? }`. lyra posts JSON-RPC to the URL.
+ * Phase 9.2 ships stdio only; HTTP lands in 9.4 polish.
+ */
+
+export interface McpServerStdio {
+  /** Server name used as the prefix in tool ids (`mcp.<name>.<tool>`). */
+  name: string
+  type?: 'stdio'
+  command: string
+  args?: string[]
+  env?: Record<string, string>
+  /** Replacement value for `${CLAUDE_PLUGIN_ROOT}` in args. Set when scanning a plugin cache. */
+  pluginRoot?: string
+}
+
+export interface McpServerHttp {
+  name: string
+  type: 'http'
+  url: string
+  headers?: Record<string, string>
+}
+
+export type McpServerConfig = McpServerStdio | McpServerHttp
+
+export interface McpToolMeta {
+  /** server name */
+  server: string
+  /** original (unprefixed) tool name advertised by the MCP server */
+  toolName: string
+  description: string
+  inputSchema: unknown
+}
+
+export interface McpDiscoveryResult {
+  servers: McpServerConfig[]
+  /** Source path the server was discovered from (debug output only). */
+  sources: { server: string; path: string }[]
+}

package/src/memory/edit.test.ts

@@ -0,0 +1,41 @@
+import { expect, test } from 'bun:test'
+import { EditError, applyEdit } from './edit'
+
+test('add on empty body inserts content', () => {
+  const out = applyEdit('', { action: 'add', newText: 'hello' })
+  expect(out).toBe('hello')
+})
+
+test('add appends with double newline on existing body', () => {
+  const out = applyEdit('first line', { action: 'add', newText: 'second line' })
+  expect(out).toBe('first line\n\nsecond line\n')
+})
+
+test('replace substring', () => {
+  const out = applyEdit('foo bar baz', {
+    action: 'replace',
+    oldText: 'bar',
+    newText: 'qux',
+  })
+  expect(out).toBe('foo qux baz')
+})
+
+test('replace throws when oldText missing', () => {
+  expect(() =>
+    applyEdit('foo bar', { action: 'replace', oldText: 'missing', newText: 'x' }),
+  ).toThrow(EditError)
+})
+
+test('replace throws when oldText is ambiguous', () => {
+  expect(() => applyEdit('foo foo', { action: 'replace', oldText: 'foo', newText: 'x' })).toThrow(
+    EditError,
+  )
+})
+
+test('remove strips matching substring', () => {
+  const out = applyEdit('leading payload trailing', {
+    action: 'remove',
+    oldText: 'payload ',
+  })
+  expect(out).toBe('leading trailing')
+})

package/src/memory/edit.ts

@@ -0,0 +1,53 @@
+export type EditAction = 'add' | 'replace' | 'remove'
+
+export interface EditOp {
+  action: EditAction
+  /** Required for replace/remove. Substring to match in the existing body. */
+  oldText?: string
+  /** Required for add/replace. Text to insert. */
+  newText?: string
+}
+
+export class EditError extends Error {
+  constructor(
+    message: string,
+    readonly op: EditOp,
+  ) {
+    super(message)
+    this.name = 'EditError'
+  }
+}
+
+/**
+ * Apply a single edit op to `body`. Substring-based matching (hermes pattern),
+ * no IDs or line numbers. Returns the new body.
+ */
+export function applyEdit(body: string, op: EditOp): string {
+  switch (op.action) {
+    case 'add': {
+      if (op.newText === undefined) throw new EditError('add requires newText', op)
+      return body.length === 0 ? op.newText : `${body.trimEnd()}\n\n${op.newText}\n`
+    }
+    case 'replace': {
+      if (op.oldText === undefined || op.newText === undefined) {
+        throw new EditError('replace requires oldText AND newText', op)
+      }
+      const idx = locateUnique(body, op.oldText, op)
+      return body.slice(0, idx) + op.newText + body.slice(idx + op.oldText.length)
+    }
+    case 'remove': {
+      if (op.oldText === undefined) throw new EditError('remove requires oldText', op)
+      const idx = locateUnique(body, op.oldText, op)
+      return body.slice(0, idx) + body.slice(idx + op.oldText.length)
+    }
+  }
+}
+
+function locateUnique(body: string, needle: string, op: EditOp): number {
+  const idx = body.indexOf(needle)
+  if (idx < 0) throw new EditError('oldText not found in body', op)
+  if (body.indexOf(needle, idx + 1) >= 0) {
+    throw new EditError('oldText is not unique in body', op)
+  }
+  return idx
+}

package/src/memory/encryption.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from 'bun:test'
+import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519'
+import {
+  MEMORY_BLOB_VERSION,
+  decryptMemoryBytes,
+  deriveMemoryKey,
+  encryptMemoryBytes,
+} from './encryption'
+
+const genSecret = (): string => Ed25519Keypair.generate().getSecretKey()
+
+describe('memory encryption', () => {
+  test('round-trip: encrypt + decrypt with same agent key', () => {
+    const agentPriv = genSecret()
+    const key = deriveMemoryKey(agentPriv)
+    const plaintext = new TextEncoder().encode('# identity\n\nagent-001 minted at block 42\n')
+    const blob = encryptMemoryBytes(plaintext, key)
+    expect(blob[0]).toBe(MEMORY_BLOB_VERSION)
+    const out = decryptMemoryBytes(blob, key)
+    expect(new TextDecoder().decode(out)).toBe(new TextDecoder().decode(plaintext))
+  })
+
+  test('different agent keys produce different ciphertexts (key separation)', () => {
+    const a = deriveMemoryKey(genSecret())
+    const b = deriveMemoryKey(genSecret())
+    const pt = new TextEncoder().encode('hello')
+    const ba = encryptMemoryBytes(pt, a)
+    const bb = encryptMemoryBytes(pt, b)
+    expect(Buffer.from(ba).equals(Buffer.from(bb))).toBe(false)
+    expect(() => decryptMemoryBytes(ba, b)).toThrow()
+  })
+
+  test('two encrypts of same plaintext yield different ciphertexts (random IV)', () => {
+    const key = deriveMemoryKey(genSecret())
+    const pt = new TextEncoder().encode('same plaintext')
+    const a = encryptMemoryBytes(pt, key)
+    const b = encryptMemoryBytes(pt, key)
+    expect(Buffer.from(a).equals(Buffer.from(b))).toBe(false)
+    expect(new TextDecoder().decode(decryptMemoryBytes(a, key))).toBe('same plaintext')
+    expect(new TextDecoder().decode(decryptMemoryBytes(b, key))).toBe('same plaintext')
+  })
+
+  test('tampered ciphertext fails GCM auth', () => {
+    const key = deriveMemoryKey(genSecret())
+    const blob = encryptMemoryBytes(new TextEncoder().encode('x'), key)
+    blob[blob.length - 1] = (blob[blob.length - 1] ?? 0) ^ 0xff
+    expect(() => decryptMemoryBytes(blob, key)).toThrow()
+  })
+
+  test('rejects unsupported version byte', () => {
+    const key = deriveMemoryKey(genSecret())
+    const blob = encryptMemoryBytes(new TextEncoder().encode('x'), key)
+    blob[0] = 99
+    expect(() => decryptMemoryBytes(blob, key)).toThrow(/unsupported memory blob version/)
+  })
+
+  test('rejects too-short blob', () => {
+    const key = deriveMemoryKey(genSecret())
+    expect(() => decryptMemoryBytes(new Uint8Array([1, 2, 3]), key)).toThrow(/too short/)
+  })
+
+  test('determinism: same agent privkey always derives same key', () => {
+    const priv = genSecret()
+    const k1 = deriveMemoryKey(priv)
+    const k2 = deriveMemoryKey(priv)
+    expect(k1.equals(k2)).toBe(true)
+  })
+})

package/src/memory/encryption.ts

@@ -0,0 +1,94 @@
+import { createCipheriv, createDecipheriv, hkdfSync, randomBytes } from 'node:crypto'
+import { gunzipSync, gzipSync } from 'node:zlib'
+
+/**
+ * Phase 6.7 memory file encryption.
+ *
+ * Key derivation: HKDF-SHA256(ikm = agent privkey bytes, info = "lyra-memory-aead-v1")
+ *   → 32-byte AES-256-GCM key.
+ *
+ * Why agent privkey (not operator wallet)? Memory writes happen mid-chat —
+ * thousands of times in a long conversation. Asking the operator wallet to
+ * sign per write would be miserable for WC users. The agent privkey is
+ * already in RAM during the chat session (decrypted via operator at session
+ * start), so deriving a memory key from it is silent and fast.
+ *
+ * Recovery: anyone who can decrypt the keystore can derive this key, so the
+ * security envelope is the same as the keystore's.
+ *
+ * Format: v(1) || iv(12) || tag(16) || ciphertext  (raw bytes, no JSON wrap).
+ *   v=1: plaintext encrypted directly (legacy).
+ *   v=2: plaintext gzip-compressed first then encrypted. Decryption gunzips
+ *        after AES-GCM. Used for the activity-log slot where JSON content
+ *        compresses 5-10x and the Walrus upload is the bottleneck.
+ *
+ * Both versions are backwards-compatible: decryptMemoryBytes dispatches on
+ * the leading version byte and reads either layout.
+ */
+export const MEMORY_BLOB_VERSION = 1 as const
+export const MEMORY_BLOB_VERSION_GZIP = 2 as const
+
+const HKDF_INFO = Buffer.from('lyra-memory-aead-v1', 'utf8')
+const KEY_LEN = 32
+const IV_LEN = 12
+const TAG_LEN = 16
+
+/**
+ * Derive the memory AES key from the agent's secret. Accepts the raw secret
+ * bytes or a string (Sui bech32 secret `suiprivkey1...`, or legacy `0x` hex);
+ * strings are keyed by their UTF-8 bytes so any stable secret representation
+ * works. The security envelope is the keystore's: whoever can decrypt the
+ * keystore can re-derive this key.
+ */
+export function deriveMemoryKey(agentSecret: string | Uint8Array): Buffer {
+  const ikm =
+    typeof agentSecret === 'string' ? Buffer.from(agentSecret, 'utf8') : Buffer.from(agentSecret)
+  return Buffer.from(hkdfSync('sha256', ikm, Buffer.alloc(0), HKDF_INFO, KEY_LEN))
+}
+
+export interface EncryptOpts {
+  /**
+   * Gzip the plaintext before encrypting. Reduces blob size 5-10x on JSON-
+   * heavy content like the activity log. Costs a few ms of CPU per upload
+   * — fine because the network upload it saves is much slower. Default
+   * false to preserve byte-for-byte compatibility with v=1 callers.
+   */
+  compress?: boolean
+}
+
+export function encryptMemoryBytes(
+  plaintext: Uint8Array,
+  key: Buffer,
+  opts: EncryptOpts = {},
+): Uint8Array {
+  if (key.length !== KEY_LEN) throw new Error(`memory key must be ${KEY_LEN} bytes`)
+  const iv = randomBytes(IV_LEN)
+  const cipher = createCipheriv('aes-256-gcm', key, iv)
+  const payload = opts.compress ? gzipSync(plaintext) : plaintext
+  const ct = Buffer.concat([cipher.update(payload), cipher.final()])
+  const tag = cipher.getAuthTag()
+  const version = opts.compress ? MEMORY_BLOB_VERSION_GZIP : MEMORY_BLOB_VERSION
+  return new Uint8Array(Buffer.concat([Buffer.from([version]), iv, tag, ct]))
+}
+
+export function decryptMemoryBytes(blob: Uint8Array, key: Buffer): Uint8Array {
+  if (key.length !== KEY_LEN) throw new Error(`memory key must be ${KEY_LEN} bytes`)
+  const buf = Buffer.from(blob)
+  if (buf.length < 1 + IV_LEN + TAG_LEN) {
+    throw new Error(`memory blob too short: ${buf.length} bytes`)
+  }
+  const version = buf[0]
+  if (version !== MEMORY_BLOB_VERSION && version !== MEMORY_BLOB_VERSION_GZIP) {
+    throw new Error(`unsupported memory blob version: ${version}`)
+  }
+  const iv = buf.subarray(1, 1 + IV_LEN)
+  const tag = buf.subarray(1 + IV_LEN, 1 + IV_LEN + TAG_LEN)
+  const ct = buf.subarray(1 + IV_LEN + TAG_LEN)
+  const decipher = createDecipheriv('aes-256-gcm', key, iv)
+  decipher.setAuthTag(tag)
+  const decrypted = Buffer.concat([decipher.update(ct), decipher.final()])
+  if (version === MEMORY_BLOB_VERSION_GZIP) {
+    return new Uint8Array(gunzipSync(decrypted))
+  }
+  return new Uint8Array(decrypted)
+}

package/src/memory/fs-util.ts

@@ -0,0 +1,15 @@
+import { readFile } from 'node:fs/promises'
+
+/**
+ * Read a file as bytes; return null on ENOENT, rethrow other errors.
+ * Used wherever an "absent file is fine, anything else is a bug" semantic
+ * is needed (memory sync, activity log sync, on-chain diff vs local).
+ */
+export async function readOrNull(path: string): Promise<Uint8Array | null> {
+  try {
+    return new Uint8Array(await readFile(path))
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') return null
+    throw e
+  }
+}

package/src/memory/index-file.ts

@@ -0,0 +1,74 @@
+import { readFile, rename, writeFile } from 'node:fs/promises'
+import type { MemoryIndex, MemoryIndexEntry } from './types'
+
+/** Max enforced by Claude Code conventions — loaded into every prompt. */
+export const INDEX_LINE_LIMIT = 200
+export const INDEX_BYTE_LIMIT = 25 * 1024
+
+const ENTRY_RE = /^-\s*\[([^\]]+)\]\(([^)]+)\)(?:\s*[-—]\s*(.*))?$/
+
+export function parseIndex(raw: string): MemoryIndex {
+  const lines = raw.split('\n')
+  const entries = new Map<string, MemoryIndexEntry>()
+  for (const line of lines) {
+    const m = line.match(ENTRY_RE)
+    if (m?.[1] && m[2]) {
+      const title = m[1]
+      const file = m[2]
+      const hook = m[3] ?? ''
+      entries.set(file, { file, title, hook: hook.trim() })
+    }
+  }
+  return { lines, entries }
+}
+
+export function stringifyIndex(index: MemoryIndex): string {
+  const joined = index.lines.join('\n')
+  return joined.endsWith('\n') ? joined : `${joined}\n`
+}
+
+export async function readIndexFile(path: string): Promise<MemoryIndex> {
+  const raw = await readFile(path, 'utf8').catch(e => {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') return ''
+    throw e
+  })
+  return parseIndex(raw)
+}
+
+export async function writeIndexFile(path: string, index: MemoryIndex): Promise<void> {
+  const content = stringifyIndex(index)
+  if (content.length > INDEX_BYTE_LIMIT) {
+    throw new Error(`MEMORY.md exceeds ${INDEX_BYTE_LIMIT}-byte cap (got ${content.length})`)
+  }
+  if (index.lines.length > INDEX_LINE_LIMIT) {
+    throw new Error(`MEMORY.md exceeds ${INDEX_LINE_LIMIT}-line cap (got ${index.lines.length})`)
+  }
+  const tmp = `${path}.tmp-${process.pid}-${Date.now().toString(36)}`
+  await writeFile(tmp, content, 'utf8')
+  await rename(tmp, path)
+}
+
+export function addEntryLine(index: MemoryIndex, entry: MemoryIndexEntry): MemoryIndex {
+  if (index.entries.has(entry.file)) return index
+  const line = `- [${entry.title}](${entry.file}) — ${entry.hook}`
+  const next: MemoryIndex = {
+    lines: [...index.lines, line],
+    entries: new Map(index.entries),
+  }
+  next.entries.set(entry.file, entry)
+  return next
+}
+
+export function removeEntryLine(index: MemoryIndex, file: string): MemoryIndex {
+  if (!index.entries.has(file)) return index
+  const filtered = index.lines.filter(line => {
+    const m = line.match(ENTRY_RE)
+    return !(m && m[2] === file)
+  })
+  const next: MemoryIndex = {
+    lines: filtered,
+    entries: new Map(index.entries),
+  }
+  next.entries.delete(file)
+  return next
+}

package/src/memory/index-sync.test.ts

@@ -0,0 +1,81 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { ensureSyntheticIndexEntries } from './index-sync'
+
+describe('ensureSyntheticIndexEntries', () => {
+  let memoryDir: string
+
+  beforeEach(() => {
+    memoryDir = mkdtempSync(join(tmpdir(), 'index-sync-'))
+    mkdirSync(join(memoryDir, 'agent'), { recursive: true })
+    mkdirSync(join(memoryDir, 'user'), { recursive: true })
+    writeFileSync(join(memoryDir, 'MEMORY.md'), '# Memory\n\n', 'utf8')
+  })
+
+  afterEach(() => {
+    if (memoryDir) rmSync(memoryDir, { recursive: true, force: true })
+  })
+
+  it('adds entries for files that exist on disk with frontmatter descriptions', async () => {
+    writeFileSync(
+      join(memoryDir, 'agent', 'identity.md'),
+      '---\nname: identity\ndescription: Auto-written agent identity facts\ntype: agent-identity\n---\n# id',
+    )
+    writeFileSync(
+      join(memoryDir, 'agent', 'persona.md'),
+      '---\nname: persona\ndescription: Voice + behavior style\ntype: agent-persona\n---\nbody',
+    )
+    writeFileSync(
+      join(memoryDir, 'user', 'profile.md'),
+      '---\nname: profile\ndescription: User profile\ntype: user\n---\nbody',
+    )
+    const r = await ensureSyntheticIndexEntries(memoryDir)
+    expect(r.added).toEqual(['agent/identity.md', 'agent/persona.md', 'user/profile.md'])
+    expect(r.skipped).toEqual([])
+    const idx = readFileSync(join(memoryDir, 'MEMORY.md'), 'utf8')
+    expect(idx).toContain('agent/identity.md')
+    expect(idx).toContain('Auto-written agent identity facts')
+    expect(idx).toContain('agent/persona.md')
+    expect(idx).toContain('user/profile.md')
+  })
+
+  it('is idempotent — second call adds nothing', async () => {
+    writeFileSync(
+      join(memoryDir, 'agent', 'identity.md'),
+      '---\nname: identity\ndescription: id desc\ntype: agent-identity\n---\nbody',
+    )
+    await ensureSyntheticIndexEntries(memoryDir)
+    const r2 = await ensureSyntheticIndexEntries(memoryDir)
+    expect(r2.added).toEqual([])
+    expect(r2.skipped).toContain('agent/identity.md')
+  })
+
+  it('skips files that do not exist on disk', async () => {
+    // Only persona exists, no identity.md or profile.md.
+    writeFileSync(
+      join(memoryDir, 'agent', 'persona.md'),
+      '---\nname: persona\ndescription: voice\ntype: agent-persona\n---\nbody',
+    )
+    const r = await ensureSyntheticIndexEntries(memoryDir)
+    expect(r.added).toEqual(['agent/persona.md'])
+    expect(r.skipped).toEqual(['agent/identity.md', 'user/profile.md'])
+  })
+
+  it('falls back to filename title when frontmatter is missing', async () => {
+    writeFileSync(join(memoryDir, 'agent', 'identity.md'), 'no frontmatter here')
+    const r = await ensureSyntheticIndexEntries(memoryDir)
+    expect(r.added).toEqual(['agent/identity.md'])
+    const idx = readFileSync(join(memoryDir, 'MEMORY.md'), 'utf8')
+    expect(idx).toContain('agent/identity.md')
+    expect(idx).toContain('identity')
+  })
+
+  it('no-ops gracefully when MEMORY.md is missing', async () => {
+    rmSync(join(memoryDir, 'MEMORY.md'))
+    const r = await ensureSyntheticIndexEntries(memoryDir)
+    expect(r.added).toEqual([])
+    expect(r.skipped.length).toBe(3)
+  })
+})