@jossuealcala/madre 0.2.0

package/src/mcp/image-server.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+// MADRE Image Studio: a tiny MCP server (stdio, JSON-RPC 2.0) that exposes one
+// tool, generate_image, backed by the Gemini API image models and the user's
+// own Gemini key. MADRE attaches it to the isolated homes of the CLIs that
+// cannot generate images natively (Gemini CLI, Claude Code, OpenCode), only
+// during a creation lease whose image scope is on. Files are written inside
+// the lease directory given in PULSE_IMAGE_OUT_DIR, never anywhere else.
+//
+// Environment:
+//   PULSE_IMAGE_OUT_DIR   required, absolute lease directory
+//   PULSE_IMAGE_MODEL     default gemini-2.5-flash-image
+//   GEMINI_API_KEY        optional; otherwise the macOS keychain entry the
+//                         Gemini CLI stores (service gemini-cli-api-key)
+//   PULSE_IMAGE_FAKE=1    write a 1×1 PNG without calling Google (tests)
+
+import { execFile } from 'node:child_process';
+import { mkdir, writeFile, realpath } from 'node:fs/promises';
+import { basename, extname, join, resolve, sep } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const SERVER_NAME = 'pulse-image';
+const SERVER_VERSION = '0.1.0';
+const DEFAULT_MODEL = 'gemini-2.5-flash-image';
+const FAKE_PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==', 'base64');
+
+export async function resolveGeminiKey(env = process.env) {
+  if (env.GEMINI_API_KEY) return env.GEMINI_API_KEY;
+  if (env.GOOGLE_API_KEY) return env.GOOGLE_API_KEY;
+  if (process.platform !== 'darwin') return null;
+  // The keychain occasionally answers empty under concurrent reads; one retry.
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const { stdout } = await execFileAsync('/usr/bin/security', ['find-generic-password', '-s', 'gemini-cli-api-key', '-w'], { timeout: 4000 });
+      const raw = stdout.trim();
+      if (!raw) continue;
+      try {
+        const parsed = JSON.parse(raw);
+        return parsed?.token?.accessToken ?? parsed?.token?.apiKey ?? parsed?.apiKey ?? null;
+      } catch {
+        return raw;
+      }
+    } catch {
+      if (attempt === 1) return null;
+    }
+  }
+  return null;
+}
+
+export function safeImageName(name, fallback = 'image.png') {
+  const cleaned = basename(String(name ?? fallback)).replace(/[^\w.\- ]+/g, '_').replace(/^\.+/, '') || fallback;
+  return extname(cleaned) ? cleaned : `${cleaned}.png`;
+}
+
+// Google's error strings, turned into something a human can act on.
+export function explainGoogleError(status, body) {
+  const message = body?.error?.message ?? '';
+  if (/prepayment credits are depleted|billing/i.test(message)) return { code: 'CREDITS_DEPLETED', message: 'Google reports the AI Studio project has no prepaid credits left. Top up at https://ai.studio/projects and try again.' };
+  if (status === 429) return { code: 'RATE_LIMITED', message: 'Google is rate-limiting this key (HTTP 429). Wait a minute and retry.' };
+  if (status === 401 || status === 403) return { code: 'AUTH', message: `Google rejected the Gemini key (HTTP ${status}). Check GEMINI_API_KEY or sign in again with the Gemini CLI.` };
+  if (status === 404) return { code: 'MODEL', message: `Image model not available to this key (HTTP 404): ${message}` };
+  return { code: 'ERROR', message: message || `Google returned HTTP ${status}.` };
+}
+
+export async function generateImage({ prompt, fileName, outDir, model = process.env.PULSE_IMAGE_MODEL || DEFAULT_MODEL, env = process.env, fetchImpl = fetch }) {
+  if (!prompt || typeof prompt !== 'string') throw Object.assign(new Error('A text prompt is required.'), { code: 'INVALID' });
+  const root = await realpath(outDir).catch(() => null);
+  if (!root) throw Object.assign(new Error('The lease directory does not exist.'), { code: 'NO_LEASE' });
+  const target = resolve(root, safeImageName(fileName));
+  if (!target.startsWith(root + sep)) throw Object.assign(new Error('The file must stay inside the lease directory.'), { code: 'INVALID' });
+  await mkdir(root, { recursive: true });
+
+  if (env.PULSE_IMAGE_FAKE === '1') {
+    await writeFile(target, FAKE_PNG);
+    return { path: target, bytes: FAKE_PNG.length, mimeType: 'image/png', model: 'fake' };
+  }
+  const key = await resolveGeminiKey(env);
+  if (!key) throw Object.assign(new Error('No Gemini API key: set GEMINI_API_KEY or sign in with the Gemini CLI (/auth → API key).'), { code: 'NO_KEY' });
+  const response = await fetchImpl(`https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(model)}:generateContent`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-goog-api-key': key },
+    body: JSON.stringify({ contents: [{ parts: [{ text: prompt }] }], generationConfig: { responseModalities: ['IMAGE'] } }),
+  });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    const explained = explainGoogleError(response.status, body);
+    throw Object.assign(new Error(explained.message), { code: explained.code, status: response.status });
+  }
+  const part = body.candidates?.[0]?.content?.parts?.find((item) => item.inlineData?.data);
+  if (!part) throw Object.assign(new Error('Google returned no image data.'), { code: 'EMPTY', detail: body.candidates?.[0]?.finishReason ?? null });
+  const bytes = Buffer.from(part.inlineData.data, 'base64');
+  const mimeType = part.inlineData.mimeType ?? 'image/png';
+  const finalPath = /jpe?g/.test(mimeType) && !/\.jpe?g$/i.test(target) ? target.replace(/\.png$/i, '.jpg') : target;
+  await writeFile(finalPath, bytes);
+  return { path: finalPath, bytes: bytes.length, mimeType, model };
+}
+
+export const TOOL = {
+  name: 'generate_image',
+  description: 'Generate an image from a text prompt with a Gemini image model and save it as a PNG inside the current creation lease directory. Returns the saved path.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      prompt: { type: 'string', description: 'What the image should show; be specific about style, colors and composition.' },
+      file_name: { type: 'string', description: 'File name for the PNG, e.g. poster.png. Saved inside the lease directory.' },
+    },
+    required: ['prompt', 'file_name'],
+  },
+};
+
+// Minimal JSON-RPC 2.0 over stdio: newline-delimited messages (MCP stdio).
+export function handleRequest(message, { outDir, env = process.env, generate = generateImage } = {}) {
+  const reply = (result) => ({ jsonrpc: '2.0', id: message.id, result });
+  const fail = (code, text) => ({ jsonrpc: '2.0', id: message.id, error: { code, message: text } });
+  switch (message.method) {
+    case 'initialize':
+      return Promise.resolve(reply({ protocolVersion: message.params?.protocolVersion ?? '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: SERVER_NAME, version: SERVER_VERSION } }));
+    case 'notifications/initialized':
+    case 'initialized':
+      return Promise.resolve(null);
+    case 'ping':
+      return Promise.resolve(reply({}));
+    case 'tools/list':
+      return Promise.resolve(reply({ tools: [TOOL] }));
+    case 'tools/call': {
+      const { name, arguments: args = {} } = message.params ?? {};
+      if (name !== TOOL.name) return Promise.resolve(fail(-32602, `Unknown tool: ${name}`));
+      return generate({ prompt: args.prompt, fileName: args.file_name, outDir, env })
+        .then((result) => reply({ content: [{ type: 'text', text: `Saved ${result.path} (${result.bytes} bytes, ${result.mimeType}, model ${result.model}).` }], isError: false }))
+        .catch((error) => reply({ content: [{ type: 'text', text: `Image generation failed (${error.code ?? 'ERROR'}): ${error.message}` }], isError: true }));
+    }
+    default:
+      return Promise.resolve(message.id === undefined ? null : fail(-32601, `Method not found: ${message.method}`));
+  }
+}
+
+export function serve({ input = process.stdin, output = process.stdout, outDir = process.env.PULSE_IMAGE_OUT_DIR, env = process.env } = {}) {
+  let buffer = '';
+  let pending = 0;
+  let ended = false;
+  const finish = () => { if (ended && pending === 0) process.exit(0); };
+  input.setEncoding('utf8');
+  input.on('data', (chunk) => {
+    buffer += chunk;
+    let index;
+    while ((index = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, index).trim();
+      buffer = buffer.slice(index + 1);
+      if (!line) continue;
+      let message;
+      try { message = JSON.parse(line); } catch { output.write(`${JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } })}\n`); continue; }
+      pending += 1;
+      void handleRequest(message, { outDir, env })
+        .then((response) => { if (response) output.write(`${JSON.stringify(response)}\n`); })
+        .finally(() => { pending -= 1; finish(); });
+    }
+  });
+  // stdin closing means the client is gone; answer what is in flight, then leave.
+  input.on('end', () => { ended = true; finish(); });
+}
+
+const invokedDirectly = process.argv[1] && (await realpath(process.argv[1]).catch(() => process.argv[1])) === (await realpath(new URL(import.meta.url).pathname).catch(() => null));
+if (invokedDirectly) {
+  if (!process.env.PULSE_IMAGE_OUT_DIR) {
+    process.stderr.write('PULSE_IMAGE_OUT_DIR is required.\n');
+    process.exit(2);
+  }
+  serve();
+}

package/src/mcp/memory-server.mjs

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+// MADRE memory: a tiny MCP server (stdio, JSON-RPC 2.0) that lets the agent in
+// a turn consult the room's memory itself: everything said outside GHOST,
+// the distilled notes, exact stretches of the ledger, and AHP+'s project
+// state. Read-only over the SQLite file MADRE keeps next to the ledger.
+//
+// Environment:
+//   PULSE_MEMORY_DB       required, the room's memory.sqlite
+//   PULSE_PROJECT_ROOT    the project, for project_state (AHP+ in .ahp/)
+//   GEMINI_API_KEY        optional; otherwise the macOS keychain entry of the
+//                         Gemini CLI. Without a key search is lexical only.
+
+import { readFile, readdir, stat, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { RoomMemory, formatRecall, formatMemories, MEMORY_KINDS } from '../memory.mjs';
+import { createEmbedder } from '../embeddings.mjs';
+import { resolveGeminiKey } from './image-server.mjs';
+
+const SERVER_NAME = 'pulse-memory';
+const SERVER_VERSION = '0.1.0';
+
+export const TOOLS = [
+  {
+    name: 'memory_search',
+    description: 'Search the room\'s durable memory: everything said in this project room outside GHOST (all agents and the human) plus the distilled notes (decisions, facts, preferences, open questions). Matches meaning as well as words. Use it before saying something was never discussed. Returns exact quotes stamped with their ledger sequence.',
+    inputSchema: { type: 'object', properties: {
+      query: { type: 'string', description: 'What you are looking for, in any language.' },
+      limit: { type: 'integer', description: 'Max quotes (1-12, default 6).' },
+      scope: { type: 'string', enum: ['all', 'quotes', 'notes'], description: 'Search quotes, notes or both (default all).' },
+    }, required: ['query'] },
+  },
+  {
+    name: 'memory_recall',
+    description: 'Read the exact text of a stretch of the room ledger by sequence numbers (as shown in [#n] stamps), e.g. to see the full message behind a quote or what was said right around it.',
+    inputSchema: { type: 'object', properties: {
+      from: { type: 'integer', description: 'First sequence to read.' },
+      through: { type: 'integer', description: 'Last sequence to read (default: from + 20).' },
+    }, required: ['from'] },
+  },
+  {
+    name: 'memory_notes',
+    description: 'List the distilled notes of this room: decisions, verified facts, the human\'s preferences and open questions, newest first, each citing its source sequences.',
+    inputSchema: { type: 'object', properties: {
+      kind: { type: 'string', enum: MEMORY_KINDS, description: 'Only this kind.' },
+      limit: { type: 'integer', description: 'Max notes (default 20).' },
+    } },
+  },
+  {
+    name: 'memory_timeline',
+    description: 'The latest exchanges of the room in order, one line each, newest first: who said what to whom, with sequence numbers.',
+    inputSchema: { type: 'object', properties: {
+      since: { type: 'integer', description: 'Only entries after this sequence.' },
+      limit: { type: 'integer', description: 'Max lines (default 30).' },
+    } },
+  },
+  {
+    name: 'memory_note',
+    description: 'Save one durable memory of this room, ONLY when the human explicitly asks you to remember, note or save something (memories are otherwise distilled automatically; never save on your own initiative). One self-contained sentence, at most 240 characters, in the language the room uses, with the ledger sequences it comes from when you know them. Refused in a GHOST turn.',
+    inputSchema: { type: 'object', properties: {
+      kind: { type: 'string', enum: MEMORY_KINDS, description: 'decision, fact, preference or question.' },
+      text: { type: 'string', description: 'The memory, one sentence, names and numbers exact.' },
+      sources: { type: 'array', items: { type: 'integer' }, description: 'Ledger sequences it comes from, if known.' },
+    }, required: ['kind', 'text'] },
+  },
+  {
+    name: 'project_state',
+    description: 'The verified project state kept by AHP+ in .ahp/ (manifest and the latest handoff), if the project uses it.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+];
+
+function clamp(n, min, max, fallback) { const value = Number(n); return Number.isFinite(value) ? Math.min(max, Math.max(min, Math.trunc(value))) : fallback; }
+
+export async function openMemory({ dbFile = process.env.PULSE_MEMORY_DB, env = process.env, keyResolver = resolveGeminiKey } = {}) {
+  if (!dbFile) throw new Error('PULSE_MEMORY_DB is required.');
+  const memory = await new RoomMemory(dbFile).initialize();
+  let embedder = null;
+  if (env.PULSE_EMBED !== '0') {
+    const key = env.PULSE_EMBED_FAKE === '1' ? null : await keyResolver(env).catch(() => null);
+    embedder = createEmbedder({ key, env });
+  }
+  memory.attachEmbedder(embedder);
+  return memory;
+}
+
+async function projectState(projectRoot) {
+  if (!projectRoot) return 'No project root was given.';
+  const ahp = join(projectRoot, '.ahp');
+  const manifest = await readFile(join(ahp, 'manifest.json'), 'utf8').catch(() => null);
+  if (manifest === null) return 'This project does not use AHP+ (no .ahp/manifest.json). The room memory tools are the durable record here.';
+  const parts = [`AHP+ manifest (.ahp/manifest.json):\n${manifest.slice(0, 4000)}`];
+  for (const dir of ['handoffs', 'sessions']) {
+    const folder = join(ahp, dir);
+    const names = await readdir(folder).catch(() => []);
+    if (!names.length) continue;
+    const dated = await Promise.all(names.map(async (name) => ({ name, mtime: (await stat(join(folder, name)).catch(() => null))?.mtimeMs ?? 0 })));
+    const latest = dated.sort((a, b) => b.mtime - a.mtime)[0];
+    const text = await readFile(join(folder, latest.name), 'utf8').catch(() => null);
+    if (text) parts.push(`Latest in .ahp/${dir}/ (${latest.name}):\n${text.slice(0, 4000)}${text.length > 4000 ? '\n…' : ''}`);
+  }
+  return parts.join('\n\n');
+}
+
+export async function callTool(name, args = {}, { memory, projectRoot = process.env.PULSE_PROJECT_ROOT, agent = process.env.PULSE_MEMORY_AGENT ?? 'agent', mode = process.env.PULSE_MEMORY_MODE ?? '1', messageId = process.env.PULSE_MEMORY_MESSAGE ?? null }) {
+  switch (name) {
+    case 'memory_note': {
+      if (String(mode) === '0') return 'This exchange is off the record (GHOST): nothing can be saved to the room memory.';
+      const text = String(args.text ?? '').replace(/\s+/g, ' ').trim();
+      if (!text) return 'Give me the memory as one sentence.';
+      if (text.length > 240) return `Too long (${text.length} characters): one sentence of at most 240.`;
+      const kind = MEMORY_KINDS.includes(args.kind) ? args.kind : 'fact';
+      const sources = (Array.isArray(args.sources) ? args.sources : []).map(Number).filter((n) => Number.isInteger(n) && n > 0);
+      const last = memory.lastSequence();
+      const before = memory.maxMemoryId();
+      const added = memory.addMemories([{ kind, text, sources }], { agent, fromSequence: sources.length ? Math.min(...sources) : last, throughSequence: sources.length ? Math.max(...sources) : last, origin: 'noted', messageId });
+      if (!added) return `Already remembered: "${text}"`;
+      const [saved] = memory.notesSince(before, { agent });
+      return `Saved memory #${saved?.id ?? '?'} (${kind}) for every future turn of this room: "${text}"`;
+    }
+    case 'memory_search': {
+      const query = String(args.query ?? '').trim();
+      if (!query) return 'Give me a query.';
+      const limit = clamp(args.limit, 1, 12, 6);
+      const scope = ['all', 'quotes', 'notes'].includes(args.scope) ? args.scope : 'all';
+      const queryVector = await memory.embedQuery(query);
+      const parts = [];
+      if (scope !== 'quotes') {
+        const notes = memory.recallMemories(query, { limit, maxChars: 2400, queryVector });
+        if (notes.length) parts.push(`Distilled notes:\n${formatMemories(notes)}`);
+      }
+      if (scope !== 'notes') {
+        const recall = memory.recall(query, { limit, maxChars: 6000, excerptChars: 480, queryVector });
+        if (recall.entries.length) parts.push(`Quotes (${queryVector ? 'meaning and words' : 'words'}; use memory_recall with a sequence to read more):\n${formatRecall(recall)}`);
+      }
+      return parts.length ? parts.join('\n\n') : `Nothing in the room memory matches "${query}". The room holds ${memory.count()} exchanges and ${memory.memoryCount()} notes.`;
+    }
+    case 'memory_recall': {
+      const from = clamp(args.from, 1, Number.MAX_SAFE_INTEGER, null);
+      if (from === null) return 'Give me a starting sequence.';
+      const through = clamp(args.through, from, from + 200, from + 20);
+      const { entries, truncated } = memory.range({ from, through });
+      if (!entries.length) return `No exchanges between #${from} and #${through}.`;
+      const lines = entries.map((entry) => `[#${entry.sequence} · ${(entry.timestamp ?? '').slice(0, 16).replace('T', ' ')} · ${entry.role === 'command' ? entry.sender : `@${entry.sender}`} (${entry.role})${entry.target && entry.target !== 'room' ? ` → ${entry.target === 'you' ? 'human' : `@${entry.target}`}` : ''}]\n${entry.text}`);
+      return `${lines.join('\n\n')}${truncated ? '\n\n[truncated; ask for a narrower range]' : ''}`;
+    }
+    case 'memory_notes': {
+      const notes = memory.memories({ limit: clamp(args.limit, 1, 100, 20), kind: MEMORY_KINDS.includes(args.kind) ? args.kind : null });
+      return notes.length ? formatMemories(notes) : 'No distilled notes yet.';
+    }
+    case 'memory_timeline': {
+      const rows = memory.timeline({ since: clamp(args.since, 0, Number.MAX_SAFE_INTEGER, 0), limit: clamp(args.limit, 1, 100, 30) });
+      return rows.length
+        ? rows.map((row) => `#${row.sequence} · ${(row.timestamp ?? '').slice(0, 16).replace('T', ' ')} · ${row.role === 'command' ? row.sender : `@${row.sender}`}${row.target && row.target !== 'room' ? ` → ${row.target === 'you' ? 'human' : `@${row.target}`}` : ''}: ${row.text.replace(/\s+/g, ' ')}`).join('\n')
+        : 'The room has no exchanges yet.';
+    }
+    case 'project_state':
+      return projectState(projectRoot);
+    default:
+      throw Object.assign(new Error(`Unknown tool: ${name}`), { code: -32602 });
+  }
+}
+
+export function handleRequest(message, context) {
+  const reply = (result) => ({ jsonrpc: '2.0', id: message.id, result });
+  const fail = (code, text) => ({ jsonrpc: '2.0', id: message.id, error: { code, message: text } });
+  switch (message.method) {
+    case 'initialize':
+      return Promise.resolve(reply({ protocolVersion: message.params?.protocolVersion ?? '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: SERVER_NAME, version: SERVER_VERSION } }));
+    case 'notifications/initialized':
+    case 'initialized':
+      return Promise.resolve(null);
+    case 'ping':
+      return Promise.resolve(reply({}));
+    case 'tools/list':
+      return Promise.resolve(reply({ tools: TOOLS }));
+    case 'tools/call': {
+      const { name, arguments: args = {} } = message.params ?? {};
+      if (!TOOLS.some((tool) => tool.name === name)) return Promise.resolve(fail(-32602, `Unknown tool: ${name}`));
+      return callTool(name, args, context)
+        .then((text) => reply({ content: [{ type: 'text', text }], isError: false }))
+        .catch((error) => reply({ content: [{ type: 'text', text: `Memory tool failed: ${error.message}` }], isError: true }));
+    }
+    default:
+      return Promise.resolve(message.id === undefined ? null : fail(-32601, `Method not found: ${message.method}`));
+  }
+}
+
+export function serve({ input = process.stdin, output = process.stdout, context }) {
+  let buffer = '';
+  let pending = 0;
+  let ended = false;
+  const finish = () => { if (ended && pending === 0) process.exit(0); };
+  input.setEncoding('utf8');
+  input.on('data', (chunk) => {
+    buffer += chunk;
+    let index;
+    while ((index = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, index).trim();
+      buffer = buffer.slice(index + 1);
+      if (!line) continue;
+      let message;
+      try { message = JSON.parse(line); } catch { output.write(`${JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } })}\n`); continue; }
+      pending += 1;
+      void handleRequest(message, context)
+        .then((response) => { if (response) output.write(`${JSON.stringify(response)}\n`); })
+        .finally(() => { pending -= 1; finish(); });
+    }
+  });
+  input.on('end', () => { ended = true; finish(); });
+}
+
+const invokedDirectly = process.argv[1] && (await realpath(process.argv[1]).catch(() => process.argv[1])) === (await realpath(new URL(import.meta.url).pathname).catch(() => null));
+if (invokedDirectly) {
+  try {
+    const memory = await openMemory();
+    serve({ context: { memory, projectRoot: process.env.PULSE_PROJECT_ROOT, agent: process.env.PULSE_MEMORY_AGENT ?? 'agent', mode: process.env.PULSE_MEMORY_MODE ?? '1', messageId: process.env.PULSE_MEMORY_MESSAGE ?? null } });
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exit(2);
+  }
+}

package/src/memory-tools.mjs

@@ -0,0 +1,34 @@
+import { fileURLToPath } from 'node:url';
+
+// How MADRE attaches the room's memory to a CLI as an MCP server, every turn:
+// the agent can search what was said, read a stretch of the ledger exactly,
+// list the distilled notes, see the latest exchanges and read AHP+'s state.
+export const MEMORY_SERVER_PATH = fileURLToPath(new URL('./mcp/memory-server.mjs', import.meta.url));
+export const MEMORY_SERVER_NAME = 'pulse-memory';
+export const MEMORY_TOOLS = ['memory_search', 'memory_recall', 'memory_notes', 'memory_timeline', 'memory_note', 'project_state'];
+
+// The same server, told who is calling: memory_note signs its notes with the
+// agent and the turn, and a GHOST turn is refused any write.
+export function memoryServerForTurn(server, { agent, messageId, mode = 1 }) {
+  if (!server) return null;
+  return { ...server, env: { ...server.env, PULSE_MEMORY_AGENT: agent, PULSE_MEMORY_MESSAGE: messageId, PULSE_MEMORY_MODE: String(mode) } };
+}
+
+export function memoryServerFor({ dbFile, projectRoot, env = process.env }) {
+  if (!dbFile || env.PULSE_MEMORY_TOOLS === '0') return null;
+  return {
+    name: MEMORY_SERVER_NAME,
+    tools: MEMORY_TOOLS,
+    command: process.execPath,
+    args: [MEMORY_SERVER_PATH],
+    env: {
+      PULSE_MEMORY_DB: dbFile,
+      PULSE_PROJECT_ROOT: projectRoot,
+      ...(env.GEMINI_API_KEY ? { GEMINI_API_KEY: env.GEMINI_API_KEY } : {}),
+      ...(env.PULSE_EMBED ? { PULSE_EMBED: env.PULSE_EMBED } : {}),
+      ...(env.PULSE_EMBED_FAKE ? { PULSE_EMBED_FAKE: env.PULSE_EMBED_FAKE } : {}),
+      ...(env.PULSE_EMBED_MODEL ? { PULSE_EMBED_MODEL: env.PULSE_EMBED_MODEL } : {}),
+      ...(env.PULSE_EMBED_DIMS ? { PULSE_EMBED_DIMS: env.PULSE_EMBED_DIMS } : {}),
+    },
+  };
+}