wendkeep 0.70.0 → 0.71.1

package/src/observer-memory-publish.mjs

@@ -0,0 +1,334 @@
+import { createHash } from 'node:crypto';
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { MAX_MEMORY_CONTENT_BYTES } from './observer-memory.mjs';
+
+export const MEMORY_OUTBOX_REL = '.brain/observer-memory-outbox';
+export const MEMORY_STATE_FILE = '.brain/observer-memory-state.json';
+const MEMORY_SCHEMA_VERSION = 1;
+const ROOT_FILES = new Set(['CORE.md', 'DIGEST.md', 'SHARED_MEMORY.md']);
+const ROOTS = [
+  '02-Sessões',
+  '04-Decisões',
+  '05-Bugs',
+  '06-Aprendizados',
+  '07-Specs',
+  '08-Mudanças',
+  '.brain',
+];
+const TRANSIENT_NAMES = new Set(['observer-memory-outbox', 'observer-outbox']);
+
+function isoNow(value) {
+  const date = value instanceof Date ? value : new Date(value || Date.now());
+  if (Number.isNaN(date.getTime())) throw new Error('captured_at inválido.');
+  return date.toISOString();
+}
+
+function hash(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function readJson(path, fallback) {
+  if (!existsSync(path)) return fallback;
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function atomicJson(path, value) {
+  mkdirSync(join(path, '..'), { recursive: true });
+  const temp = path + '.' + process.pid + '.' + Date.now() + '.tmp';
+  writeFileSync(temp, JSON.stringify(value, null, 2) + '\n', 'utf8');
+  renameSync(temp, path);
+}
+
+function readState(vaultBase) {
+  return readJson(join(vaultBase, MEMORY_STATE_FILE), {
+    schema_version: MEMORY_SCHEMA_VERSION,
+    files: {},
+  });
+}
+
+function entityType(logicalPath) {
+  if (logicalPath.startsWith('02-Sessões/')) return 'session';
+  if (logicalPath.startsWith('04-Decisões/')) return 'decision';
+  if (logicalPath.startsWith('05-Bugs/')) return 'bug';
+  if (logicalPath.startsWith('06-Aprendizados/')) return 'learning';
+  if (logicalPath.startsWith('07-Specs/')) return 'spec';
+  if (logicalPath.startsWith('08-Mudanças/')) return 'change';
+  return 'memory';
+}
+
+function shouldSkip(name, relativePath) {
+  if (TRANSIENT_NAMES.has(name) || name.endsWith('.tmp') || name.endsWith('.lock')) return true;
+  if (relativePath === MEMORY_STATE_FILE) return true;
+  return false;
+}
+
+function walkDirectory(root, relativeRoot, output) {
+  if (!existsSync(root)) return;
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const logicalPath = relativeRoot ? relativeRoot + '/' + entry.name : entry.name;
+    if (shouldSkip(entry.name, logicalPath)) continue;
+    const absolute = join(root, entry.name);
+    if (entry.isDirectory()) {
+      walkDirectory(absolute, logicalPath, output);
+    } else if (entry.isFile()) {
+      output.push({ absolute, logicalPath });
+    }
+  }
+}
+
+function memoryFiles(vaultBase) {
+  const files = [];
+  for (const root of ROOTS) {
+    const absolute = join(vaultBase, root);
+    if (root === '.brain' || root.includes('-')) walkDirectory(absolute, root, files);
+  }
+  for (const rootFile of ROOT_FILES) {
+    const absolute = join(vaultBase, rootFile);
+    if (existsSync(absolute) && statSync(absolute).isFile()) files.push({ absolute, logicalPath: rootFile });
+  }
+  return files.sort((a, b) => a.logicalPath.localeCompare(b.logicalPath));
+}
+
+export function localMemoryManifest(vaultBase) {
+  return Object.fromEntries(memoryFiles(vaultBase).map((file) => {
+    const content = readFileSync(file.absolute, 'utf8');
+    return [file.logicalPath, {
+      logical_path: file.logicalPath,
+      content_hash: hash(content),
+      bytes: Buffer.byteLength(content, 'utf8'),
+    }];
+  }));
+}
+
+function projectIdFromVault(vaultBase) {
+  const project = readJson(join(vaultBase, '.brain', 'PROJECT.json'), null);
+  return project?.projectId || project?.project_id || '';
+}
+
+function eventId(projectId, logicalPath, revision, contentHash) {
+  return 'mem-' + hash([projectId, logicalPath, revision, contentHash].join(':')).slice(0, 24);
+}
+
+function makeEvent({ projectId, logicalPath, content, revision, sourceSessionId, sourceTurnId, capturedAt, operation = 'upsert' }) {
+  const body = content || '';
+  const contentHash = hash(body);
+  return {
+    schema_version: MEMORY_SCHEMA_VERSION,
+    event_id: eventId(projectId, logicalPath, revision, contentHash),
+    project_id: projectId,
+    entity_type: entityType(logicalPath),
+    logical_path: logicalPath,
+    operation,
+    ...(operation === 'upsert' ? { content: body } : {}),
+    content_hash: contentHash,
+    revision,
+    source_session_id: String(sourceSessionId || ''),
+    source_turn_id: String(sourceTurnId || ''),
+    captured_at: capturedAt,
+  };
+}
+
+export function buildMemoryEventBatch({
+  vaultBase,
+  projectId = projectIdFromVault(vaultBase),
+  sourceSessionId = '',
+  sourceTurnId = '',
+  now = new Date(),
+  state = readState(vaultBase),
+} = {}) {
+  if (!vaultBase || !projectId) throw new Error('vaultBase e projectId são obrigatórios.');
+  const capturedAt = isoNow(now);
+  const currentFiles = memoryFiles(vaultBase);
+  const currentPaths = new Set(currentFiles.map((file) => file.logicalPath));
+  const nextState = {
+    schema_version: MEMORY_SCHEMA_VERSION,
+    files: { ...(state.files || {}) },
+  };
+  const events = [];
+
+  for (const file of currentFiles) {
+    const content = readFileSync(file.absolute, 'utf8');
+    if (Buffer.byteLength(content, 'utf8') > MAX_MEMORY_CONTENT_BYTES) {
+      throw new Error('arquivo excede o limite de memória: ' + file.logicalPath);
+    }
+    const contentHash = hash(content);
+    const previous = state.files?.[file.logicalPath];
+    if (previous?.content_hash === contentHash) {
+      nextState.files[file.logicalPath] = previous;
+      continue;
+    }
+    const revision = Number(previous?.revision || 0) + 1;
+    const next = { content_hash: contentHash, revision, event_id: eventId(projectId, file.logicalPath, revision, contentHash) };
+    nextState.files[file.logicalPath] = next;
+    events.push(makeEvent({
+      projectId,
+      logicalPath: file.logicalPath,
+      content,
+      revision,
+      sourceSessionId,
+      sourceTurnId,
+      capturedAt,
+    }));
+  }
+
+  for (const [logicalPath, previous] of Object.entries(state.files || {})) {
+    if (currentPaths.has(logicalPath)) continue;
+    const revision = Number(previous.revision || 0) + 1;
+    events.push(makeEvent({
+      projectId,
+      logicalPath,
+      content: '',
+      revision,
+      sourceSessionId,
+      sourceTurnId,
+      capturedAt,
+      operation: 'delete',
+    }));
+    delete nextState.files[logicalPath];
+  }
+
+  return { events, nextState, scanned: currentFiles.length, changed: events.length };
+}
+
+export function commitMemoryPublishState(vaultBase, state) {
+  atomicJson(join(vaultBase, MEMORY_STATE_FILE), state);
+}
+
+function outboxDir(vaultBase) {
+  return join(vaultBase, MEMORY_OUTBOX_REL);
+}
+
+function outboxPath(vaultBase, events) {
+  const id = hash(JSON.stringify(events)).slice(0, 24);
+  return join(outboxDir(vaultBase), id + '.json');
+}
+
+function queueMemoryBatch(vaultBase, events) {
+  mkdirSync(outboxDir(vaultBase), { recursive: true });
+  const path = outboxPath(vaultBase, events);
+  if (!existsSync(path)) atomicJson(path, { schema_version: MEMORY_SCHEMA_VERSION, events });
+  return path;
+}
+
+export function listMemoryOutbox(vaultBase) {
+  const dir = outboxDir(vaultBase);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => name.endsWith('.json'))
+    .sort()
+    .map((name) => join(dir, name));
+}
+
+async function postBatch(url, projectId, events, fetchImpl = globalThis.fetch) {
+  const response = await fetchImpl(
+    String(url).replace(/\/$/, '') + '/v1/projects/' + encodeURIComponent(projectId) + '/memory/events',
+    {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify({ events }),
+    },
+  );
+  if (!response.ok) throw new Error('Observer respondeu HTTP ' + response.status + '.');
+  return response.json();
+}
+
+export async function retryObserverMemoryOutbox({
+  vaultBase,
+  projectId = projectIdFromVault(vaultBase),
+  url,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const files = listMemoryOutbox(vaultBase);
+  if (!url) return { attempted: 0, confirmed: 0, pending: files.length };
+  let attempted = 0;
+  let confirmed = 0;
+  for (const path of files) {
+    attempted += 1;
+    try {
+      const batch = readJson(path, null);
+      if (!batch?.events?.length) {
+        unlinkSync(path);
+        continue;
+      }
+      await postBatch(url, projectId, batch.events, fetchImpl);
+      unlinkSync(path);
+      confirmed += 1;
+    } catch {
+      break;
+    }
+  }
+  return { attempted, confirmed, pending: listMemoryOutbox(vaultBase).length };
+}
+
+export async function compareMemoryParity({
+  vaultBase,
+  projectId = projectIdFromVault(vaultBase),
+  url,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const response = await fetchImpl(
+    String(url).replace(/\/$/, '') + '/v1/projects/' + encodeURIComponent(projectId) + '/memory/tree',
+    { headers: { accept: 'application/json' } },
+  );
+  if (!response.ok) throw new Error('Observer respondeu HTTP ' + response.status + '.');
+  const body = await response.json();
+  const local = localMemoryManifest(vaultBase);
+  const remote = Object.fromEntries((body.documents || []).map((item) => [item.logical_path, item]));
+  const missing = Object.keys(local).filter((path) => !remote[path]);
+  const mismatched = Object.keys(local).filter((path) => remote[path] && remote[path].content_hash !== local[path].content_hash);
+  const extra = Object.keys(remote).filter((path) => !local[path]);
+  return {
+    files: Object.keys(local).length,
+    remote_files: Object.keys(remote).length,
+    missing: missing.length,
+    mismatched: mismatched.length,
+    extra: extra.length,
+    missing_paths: missing,
+    mismatched_paths: mismatched,
+    extra_paths: extra,
+  };
+}
+
+export async function publishObserverMemory({
+  vaultBase,
+  projectId = projectIdFromVault(vaultBase),
+  url,
+  sourceSessionId = '',
+  sourceTurnId = '',
+  now = new Date(),
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  if (!vaultBase || !projectId) throw new Error('vaultBase e projectId são obrigatórios.');
+  await retryObserverMemoryOutbox({ vaultBase, projectId, url, fetchImpl });
+  const state = readState(vaultBase);
+  const batch = buildMemoryEventBatch({ vaultBase, projectId, sourceSessionId, sourceTurnId, now, state });
+  if (batch.events.length === 0) {
+    commitMemoryPublishState(vaultBase, batch.nextState);
+    return { ok: true, queued: false, scanned: batch.scanned, changed: 0, pending: listMemoryOutbox(vaultBase).length };
+  }
+  if (!url) {
+    queueMemoryBatch(vaultBase, batch.events);
+    commitMemoryPublishState(vaultBase, batch.nextState);
+    return { ok: false, queued: true, scanned: batch.scanned, changed: batch.changed, pending: listMemoryOutbox(vaultBase).length, hookExitCode: 0 };
+  }
+  try {
+    await postBatch(url, projectId, batch.events, fetchImpl);
+    commitMemoryPublishState(vaultBase, batch.nextState);
+    return { ok: true, queued: false, scanned: batch.scanned, changed: batch.changed, pending: listMemoryOutbox(vaultBase).length };
+  } catch (error) {
+    queueMemoryBatch(vaultBase, batch.events);
+    commitMemoryPublishState(vaultBase, batch.nextState);
+    return { ok: false, queued: true, scanned: batch.scanned, changed: batch.changed, pending: listMemoryOutbox(vaultBase).length, hookExitCode: 0, error: error.message };
+  }
+}

package/src/observer-memory.mjs

@@ -0,0 +1,308 @@
+import { createHash } from 'node:crypto';
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join, relative, sep } from 'node:path';
+
+export const MEMORY_SCHEMA_VERSION = 1;
+export const MEMORY_EVENTS_FILE = 'MEMORY_EVENTS.jsonl';
+export const MEMORY_INDEX_FILE = 'MEMORY_INDEX.json';
+export const MEMORY_ROOT = 'memory';
+export const MAX_MEMORY_CONTENT_BYTES = 2 * 1024 * 1024;
+export const MEMORY_MODES = new Set(['mirror', 'container-read', 'container-authority']);
+
+const ENTITY_TYPES = new Set(['session', 'decision', 'bug', 'learning', 'spec', 'change', 'memory']);
+const OPERATIONS = new Set(['upsert', 'delete']);
+const PROJECT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,120}$/;
+const ROOTS = [
+  '02-Sessões/',
+  '04-Decisões/',
+  '05-Bugs/',
+  '06-Aprendizados/',
+  '07-Specs/',
+  '08-Mudanças/',
+  '.brain/',
+];
+const ROOT_FILES = new Set(['CORE.md', 'DIGEST.md', 'SHARED_MEMORY.md']);
+
+function hashContent(content) {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+function atomicJson(path, value) {
+  const temp = path + '.' + process.pid + '.' + Date.now() + '.tmp';
+  writeFileSync(temp, JSON.stringify(value, null, 2) + '\n', 'utf8');
+  renameSync(temp, path);
+}
+
+function readJson(path, fallback) {
+  if (!existsSync(path)) return fallback;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function ensureDataDir(dataDir) {
+  if (!dataDir) throw new Error('dataDir é obrigatório.');
+  mkdirSync(dataDir, { recursive: true });
+}
+
+function projectIdValid(projectId) {
+  return typeof projectId === 'string' && PROJECT_ID_RE.test(projectId);
+}
+
+function normalizedLogicalPath(value) {
+  const original = String(value ?? '');
+  const normalized = original.replaceAll('\\', '/').replace(/^\/+/, '');
+  if (!normalized || /^[A-Za-z]:\//.test(normalized) || original.startsWith('/') || original.startsWith('\\')) {
+    return '';
+  }
+  const parts = normalized.split('/');
+  if (parts.some((part) => !part || part === '.' || part === '..')) return '';
+  if (!(ROOT_FILES.has(normalized) || ROOTS.some((root) => normalized.startsWith(root)))) return '';
+  return normalized;
+}
+
+function memoryFilePath(dataDir, projectId, logicalPath) {
+  const base = join(dataDir, MEMORY_ROOT, projectId);
+  const target = join(base, ...logicalPath.split('/'));
+  const rel = relative(base, target);
+  if (rel.startsWith('..' + sep) || rel === '..' || /^[A-Za-z]:/.test(rel)) {
+    throw new Error('logical_path fora do projeto.');
+  }
+  return target;
+}
+
+function defaultIndex() {
+  return {
+    schema_version: MEMORY_SCHEMA_VERSION,
+    generated_at: new Date().toISOString(),
+    projects: {},
+  };
+}
+
+function loadIndex(dataDir) {
+  ensureDataDir(dataDir);
+  const index = readJson(join(dataDir, MEMORY_INDEX_FILE), null);
+  if (index?.schema_version === MEMORY_SCHEMA_VERSION && index.projects && typeof index.projects === 'object') {
+    return index;
+  }
+  return defaultIndex();
+}
+
+function saveIndex(dataDir, index) {
+  index.generated_at = new Date().toISOString();
+  atomicJson(join(dataDir, MEMORY_INDEX_FILE), index);
+}
+
+function readEventLines(dataDir) {
+  const path = join(dataDir, MEMORY_EVENTS_FILE);
+  if (!existsSync(path)) return [];
+  return readFileSync(path, 'utf8')
+    .replace(/\r\n/g, '\n')
+    .split('\n')
+    .filter((line) => line.trim())
+    .flatMap((line) => {
+      try { return [JSON.parse(line)]; } catch { return []; }
+    });
+}
+
+function projectState(index, projectId) {
+  if (!index.projects[projectId]) {
+    index.projects[projectId] = {
+      project_id: projectId,
+      mode: 'mirror',
+      documents: {},
+      event_count: 0,
+      conflict_count: 0,
+      last_event_at: '',
+    };
+  }
+  return index.projects[projectId];
+}
+
+function eventPayload(event) {
+  const clone = { ...event };
+  delete clone.event_id;
+  return JSON.stringify(clone);
+}
+
+export function validateMemoryEvent(event) {
+  const errors = [];
+  if (!event || typeof event !== 'object' || Array.isArray(event)) {
+    return { ok: false, errors: ['evento deve ser um objeto JSON.'] };
+  }
+  if (event.schema_version !== MEMORY_SCHEMA_VERSION) errors.push('schema_version incompatível.');
+  if (typeof event.event_id !== 'string' || !event.event_id.trim()) errors.push('event_id ausente.');
+  if (!projectIdValid(event.project_id)) errors.push('project_id inválido.');
+  if (!ENTITY_TYPES.has(event.entity_type)) errors.push('entity_type inválido.');
+  const path = normalizedLogicalPath(event.logical_path);
+  if (!path) errors.push('logical_path inválido ou fora das raízes autorizadas.');
+  if (!OPERATIONS.has(event.operation)) errors.push('operation inválida.');
+  if (!Number.isInteger(event.revision) || event.revision < 1) errors.push('revision inválida.');
+  if (typeof event.content_hash !== 'string' || !/^[a-f0-9]{64}$/.test(event.content_hash)) {
+    errors.push('content_hash inválido.');
+  }
+  if (typeof event.captured_at !== 'string' || Number.isNaN(Date.parse(event.captured_at))) {
+    errors.push('captured_at inválido.');
+  }
+  if (event.operation === 'upsert') {
+    if (typeof event.content !== 'string') errors.push('content ausente.');
+    else {
+      if (Buffer.byteLength(event.content, 'utf8') > MAX_MEMORY_CONTENT_BYTES) errors.push('content excede o limite.');
+      if (event.content_hash !== hashContent(event.content)) errors.push('content_hash não corresponde ao conteúdo.');
+    }
+  }
+  return { ok: errors.length === 0, errors, logical_path: path };
+}
+
+export function applyMemoryEvent(dataDir, event) {
+  ensureDataDir(dataDir);
+  const validation = validateMemoryEvent(event);
+  if (!validation.ok) return { accepted: false, errors: validation.errors };
+  const index = loadIndex(dataDir);
+  const state = projectState(index, event.project_id);
+  const existingEvent = readEventLines(dataDir).find((item) => item.event_id === event.event_id);
+  if (existingEvent) {
+    if (eventPayload(existingEvent) === eventPayload(event)) {
+      return { accepted: false, duplicate: true, event_id: event.event_id };
+    }
+    state.conflict_count += 1;
+    saveIndex(dataDir, index);
+    return { accepted: false, conflict: true, errors: ['event_id reutilizado com payload diferente.'] };
+  }
+
+  const current = state.documents[validation.logical_path];
+  if (current && event.revision < current.revision) {
+    state.conflict_count += 1;
+    saveIndex(dataDir, index);
+    return { accepted: false, conflict: true, stale: true, errors: ['revisão antiga não pode substituir a atual.'] };
+  }
+  if (current && event.revision === current.revision && current.content_hash !== event.content_hash) {
+    state.conflict_count += 1;
+    saveIndex(dataDir, index);
+    return { accepted: false, conflict: true, errors: ['revisão já possui conteúdo diferente.'] };
+  }
+
+  const path = memoryFilePath(dataDir, event.project_id, validation.logical_path);
+  if (event.operation === 'delete') {
+    rmSync(path, { force: true });
+    delete state.documents[validation.logical_path];
+  } else {
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = path + '.' + process.pid + '.' + Date.now() + '.tmp';
+    writeFileSync(temp, event.content, 'utf8');
+    renameSync(temp, path);
+    state.documents[validation.logical_path] = {
+      project_id: event.project_id,
+      logical_path: validation.logical_path,
+      entity_type: event.entity_type,
+      content_hash: event.content_hash,
+      revision: event.revision,
+      source_session_id: String(event.source_session_id || ''),
+      source_turn_id: String(event.source_turn_id || ''),
+      captured_at: event.captured_at,
+      bytes: Buffer.byteLength(event.content, 'utf8'),
+    };
+  }
+  appendFileSync(join(dataDir, MEMORY_EVENTS_FILE), JSON.stringify(event) + '\n', 'utf8');
+  state.event_count += 1;
+  state.last_event_at = event.captured_at;
+  saveIndex(dataDir, index);
+  return { accepted: true, duplicate: false, event_id: event.event_id, document: state.documents[validation.logical_path] || null };
+}
+
+export function readMemoryTree(dataDir, projectId, prefix = '') {
+  const index = loadIndex(dataDir);
+  const state = index.projects[projectId] || projectState(index, projectId);
+  const normalizedPrefix = String(prefix || '').replaceAll('\\', '/').replace(/^\/+|\/+$/g, '');
+  const documents = Object.values(state.documents)
+    .filter((item) => !normalizedPrefix || item.logical_path.startsWith(normalizedPrefix + '/') || item.logical_path === normalizedPrefix)
+    .sort((a, b) => a.logical_path.localeCompare(b.logical_path));
+  return {
+    schema_version: MEMORY_SCHEMA_VERSION,
+    project_id: projectId,
+    documents,
+    document_count: documents.length,
+    categories: [...new Set(documents.map((item) => item.logical_path.split('/')[0]))].sort(),
+  };
+}
+
+export function setMemoryMode(dataDir, projectId, mode) {
+  if (!MEMORY_MODES.has(mode)) {
+    const error = new Error('modo de memória inválido.');
+    error.code = 'invalid_memory_mode';
+    throw error;
+  }
+  const index = loadIndex(dataDir);
+  const state = projectState(index, projectId);
+  state.mode = mode;
+  saveIndex(dataDir, index);
+  return readMemorySync(dataDir, projectId);
+}
+
+export function readMemoryDocument(dataDir, projectId, logicalPath) {
+  const path = normalizedLogicalPath(logicalPath);
+  if (!projectIdValid(projectId) || !path) {
+    const error = new Error('documento inválido.');
+    error.code = 'invalid_memory_path';
+    throw error;
+  }
+  const index = loadIndex(dataDir);
+  const metadata = index.projects[projectId]?.documents?.[path];
+  if (!metadata) {
+    const error = new Error('documento não encontrado.');
+    error.code = 'memory_not_found';
+    throw error;
+  }
+  return { ...metadata, content: readFileSync(memoryFilePath(dataDir, projectId, path), 'utf8') };
+}
+
+export function exportMemoryBundle(dataDir, projectId) {
+  const tree = readMemoryTree(dataDir, projectId);
+  return {
+    schema_version: MEMORY_SCHEMA_VERSION,
+    project_id: projectId,
+    mode: readMemorySync(dataDir, projectId).mode,
+    documents: tree.documents.map((metadata) => ({
+      ...metadata,
+      content: readMemoryDocument(dataDir, projectId, metadata.logical_path).content,
+    })),
+  };
+}
+
+export function searchMemory(dataDir, projectId, query) {
+  const term = String(query || '').trim().toLowerCase();
+  if (!term) return [];
+  return readMemoryTree(dataDir, projectId).documents.flatMap((metadata) => {
+    let content;
+    try { content = readFileSync(memoryFilePath(dataDir, projectId, metadata.logical_path), 'utf8'); } catch { return []; }
+    const haystack = metadata.logical_path + '\n' + content;
+    const at = haystack.toLowerCase().indexOf(term);
+    if (at < 0) return [];
+    const start = Math.max(0, at - 80);
+    return [{ ...metadata, excerpt: haystack.slice(start, start + 240).replace(/\s+/g, ' ').trim() }];
+  });
+}
+
+export function readMemorySync(dataDir, projectId) {
+  const index = loadIndex(dataDir);
+  const state = index.projects[projectId] || projectState(index, projectId);
+  return {
+    project_id: projectId,
+    mode: state.mode || 'mirror',
+    document_count: Object.keys(state.documents).length,
+    event_count: Number(state.event_count || 0),
+    conflict_count: Number(state.conflict_count || 0),
+    pending_count: 0,
+    last_event_at: state.last_event_at || '',
+  };
+}