@johpaz/hive-sdk 0.2.0 → 0.3.0

package/packages/core/src/services/images.ts

@@ -0,0 +1,212 @@
+/**
+ * Imágenes como servicio — para el usuario final, no para el agente.
+ *
+ * Las tools de `tools/images/` existen para que el agente manipule imágenes
+ * dentro de un turno, y trabajan con ids de artefacto porque devolverle bytes a
+ * un modelo es lo que llena la ventana de contexto.
+ *
+ * Esto es lo otro: la superficie para que una aplicación ofrezca "convertí y
+ * redimensioná tus imágenes" como funcionalidad propia. **Entra y sale por
+ * bytes** —una app móvil o web sube un archivo y descarga el resultado— y por
+ * dentro se persiste como artefacto para que exista una galería y un historial.
+ *
+ * La retención la decide el usuario. Los artefactos internos se limpian solos a
+ * los 7 días, pero lo que alguien sube o transforma nace **sin expiración**:
+ * borrárselo a la semana convertiría un servicio en una pérdida de datos.
+ */
+
+import { measureImage, transformImage, type ImageFormat, type TransformOptions, imagesSupported } from "../images/index.ts";
+import {
+  createArtifact, readArtifactBytes, listArtifacts, setArtifactRetention, deleteArtifact,
+} from "../artifacts/store.ts";
+import type { ArtifactDoc } from "../storage/collections.ts";
+import { resolveUserId } from "../storage/onboarding.ts";
+import { logger } from "../utils/logger.ts";
+
+const log = logger.child("services/images");
+
+/** Lo que ve la UI de una imagen guardada. Nunca incluye los bytes. */
+export interface StoredImage {
+  id: string;
+  mimeType: string;
+  width: number | null;
+  height: number | null;
+  bytes: number;
+  createdAt: number;
+  /** `null` = no expira. */
+  expiresAt: number | null;
+}
+
+export type ImageInput = Uint8Array | ArrayBuffer | Buffer | string;
+
+function toSummary(doc: ArtifactDoc): StoredImage {
+  return {
+    id: doc.id,
+    mimeType: doc.mime_type,
+    width: doc.width,
+    height: doc.height,
+    bytes: doc.size,
+    createdAt: doc.created_at,
+    expiresAt: doc.expires_at,
+  };
+}
+
+function toBytes(input: ImageInput): Uint8Array {
+  if (typeof input === "string") return Uint8Array.from(Buffer.from(input, "base64"));
+  if (input instanceof Uint8Array) return input;
+  return new Uint8Array(input as ArrayBuffer);
+}
+
+async function owner(userId?: string): Promise<string> {
+  if (userId) return userId;
+  return (await resolveUserId({}).catch(() => null)) ?? "";
+}
+
+function requireSupport(): void {
+  if (!imagesSupported()) {
+    throw new Error("El procesamiento de imágenes necesita Bun >= 1.4 (Bun.Image no está disponible)");
+  }
+}
+
+export interface UploadOptions {
+  userId?: string;
+  mimeType?: string;
+  /** Cuándo caduca. Por omisión **nunca**: es del usuario, no basura transitoria. */
+  expiresAt?: number | null;
+}
+
+/** Guarda una imagen y devuelve su ficha. Acepta bytes o base64. */
+export async function uploadImage(input: ImageInput, opts: UploadOptions = {}): Promise<StoredImage> {
+  requireSupport();
+  const bytes = toBytes(input);
+  const meta = await measureImage(bytes);
+
+  const doc = await createArtifact({
+    bytes,
+    mimeType: opts.mimeType ?? `image/${meta.format}`,
+    kind: "image",
+    userId: await owner(opts.userId),
+    width: meta.width,
+    height: meta.height,
+    expiresAt: opts.expiresAt !== undefined ? opts.expiresAt : null,
+  });
+  return toSummary(doc);
+}
+
+export interface TransformResult extends StoredImage {
+  /** Los bytes del resultado, para que la UI los descargue sin otra llamada. */
+  data: Uint8Array;
+}
+
+/**
+ * De dónde sale la imagen: una ya guardada o datos crudos.
+ *
+ * Es explícito a propósito. La alternativa —aceptar un `string` y adivinar si es
+ * un id o un base64 por su longitud— funciona hasta que alguien manda una imagen
+ * de 4×4 píxeles, cuyo base64 es más corto que un UUID.
+ */
+export type TransformSource = { imageId: string } | { data: ImageInput };
+
+export interface ServiceTransformOptions extends TransformOptions {
+  userId?: string;
+  expiresAt?: number | null;
+}
+
+/**
+ * Transforma una imagen y guarda el resultado como una nueva.
+ *
+ * Acepta un id de una imagen ya guardada o bytes sueltos, y devuelve **la ficha
+ * y los bytes**: una UI que acaba de pedir una conversión quiere el archivo, no
+ * tener que ir a buscarlo. El original nunca se modifica.
+ */
+export async function transformStoredImage(
+  source: TransformSource,
+  opts: ServiceTransformOptions = {},
+): Promise<TransformResult> {
+  requireSupport();
+
+  let entrada: Uint8Array;
+  if ("imageId" in source) {
+    const datos = await readArtifactBytes(source.imageId);
+    if (!datos) throw new Error(`No encontré la imagen ${source.imageId}`);
+    entrada = datos.bytes;
+  } else {
+    entrada = toBytes(source.data);
+  }
+
+  const { bytes, metadata } = await transformImage(entrada, opts);
+  const doc = await createArtifact({
+    bytes,
+    mimeType: `image/${metadata.format}`,
+    kind: "image",
+    userId: await owner(opts.userId),
+    width: metadata.width,
+    height: metadata.height,
+    expiresAt: opts.expiresAt !== undefined ? opts.expiresAt : null,
+  });
+
+  log.info(`imagen transformada → ${doc.id} (${metadata.width}x${metadata.height} ${metadata.format})`);
+  return { ...toSummary(doc), data: bytes };
+}
+
+/** Los bytes de una imagen guardada, para descargarla. */
+export async function getImageBytes(
+  imageId: string,
+): Promise<{ data: Uint8Array; mimeType: string } | null> {
+  const datos = await readArtifactBytes(imageId);
+  return datos ? { data: new Uint8Array(datos.bytes), mimeType: datos.mimeType } : null;
+}
+
+/** La galería del usuario, de la más reciente a la más vieja. */
+export async function listImages(
+  userId?: string,
+  opts: { limit?: number; includeExpired?: boolean } = {},
+): Promise<StoredImage[]> {
+  const docs = await listArtifacts(await owner(userId), { kind: "image", ...opts });
+  return docs.map(toSummary);
+}
+
+/**
+ * Cambia cuándo caduca. `null` = conservarla indefinidamente.
+ *
+ * Es el control que pediste: el usuario decide qué guarda y qué deja ir.
+ */
+export async function setImageRetention(imageId: string, expiresAt: number | null): Promise<StoredImage> {
+  const doc = await setArtifactRetention(imageId, expiresAt);
+  if (!doc) throw new Error(`No encontré la imagen ${imageId}`);
+  return toSummary(doc);
+}
+
+/** Borra la imagen y su archivo, ahora. */
+export async function deleteImage(imageId: string): Promise<boolean> {
+  return deleteArtifact(imageId);
+}
+
+// ─── Presets ─────────────────────────────────────────────────────────────────
+
+/**
+ * Tamaños de uso corriente, para que quien monte la UI no tenga que decidir
+ * cuánto es "una miniatura". Son un punto de partida, no una imposición:
+ * `transformStoredImage` acepta cualquier combinación.
+ */
+export const IMAGE_PRESETS = {
+  /** Vista en cuadrícula. */
+  thumbnail: { width: 256, height: 256, format: "webp" as ImageFormat, quality: 75 },
+  /** Publicar en una página sin que pese de más. */
+  web: { width: 1600, format: "webp" as ImageFormat, quality: 82 },
+  /** Foto de perfil. */
+  avatar: { width: 512, height: 512, format: "webp" as ImageFormat, quality: 85 },
+} as const;
+
+export type ImagePreset = keyof typeof IMAGE_PRESETS;
+
+/** Aplica un preset. Atajo sobre `transformStoredImage`. */
+export async function applyPreset(
+  source: TransformSource,
+  preset: ImagePreset,
+  opts: { userId?: string; expiresAt?: number | null } = {},
+): Promise<TransformResult> {
+  const p = IMAGE_PRESETS[preset];
+  if (!p) throw new Error(`Preset desconocido: ${preset}. Disponibles: ${Object.keys(IMAGE_PRESETS).join(", ")}`);
+  return transformStoredImage(source, { ...p, ...opts });
+}

package/packages/core/src/services/index.ts

@@ -0,0 +1,112 @@
+/**
+ * Services — la superficie que maneja una interfaz, no el modelo.
+ *
+ * El SDK nació para que lo condujera un LLM: casi todo el CRUD vivía dentro de
+ * las tools (`cronCreateTool`, `memoryWriteTool`, `agentCreateTool`…), con
+ * argumentos con forma de LLM y respuestas escritas para un prompt. Montar una
+ * UI encima obligaba a llamar `tool.execute({...})` y parsear prosa, o a
+ * escribir consultas crudas contra HiveDB conociendo un esquema privado.
+ *
+ * Acá vive la implementación y las tools pasan a envolverla: una sola
+ * implementación con dos consumidores, el modelo y la aplicación.
+ *
+ * Es deliberadamente **agnóstico del framework** — funciones, no rutas HTTP.
+ * Una app móvil o de escritorio que embeba el runtime no quiere un servidor; y
+ * quien haga una UI web monta sus rutas encima en unas pocas líneas, que es
+ * exactamente lo que hace hive (ver `gateway/routes/conversations.ts`, delgada
+ * porque toda su lógica está en `agent/thread-store.ts`).
+ *
+ * Convención: estas funciones **lanzan** ante un error en vez de devolver
+ * `{ok:false}`. Quien construye una UI quiere `try/catch`, no inspeccionar un
+ * campo. La traducción al formato del modelo la hace el envoltorio de la tool.
+ */
+
+export * as memory from "./memory.ts";
+export * as agents from "./agents.ts";
+export * as skills from "./skills.ts";
+export * as cron from "./cron.ts";
+export * as tools from "./tools.ts";
+export * as ethics from "./ethics.ts";
+export * as providers from "./providers.ts";
+export * as models from "./models.ts";
+export * as mcp from "./mcp.ts";
+export * as swarms from "./swarms.ts";
+export * as endpoints from "./endpoints.ts";
+export * as setup from "./setup.ts";
+export * as images from "./images.ts";
+
+// También sueltas, para quien prefiera importar la función directa.
+export {
+  writeMemory, readMemory, listMemories, searchMemories, deleteMemory,
+  type MemoryEntry, type MemorySearchHit,
+} from "./memory.ts";
+
+export {
+  createAgent, getAgent, listAgents, updateAgent, deleteAgent,
+  assignTools, assignSkills, assignMcpServers, enableAgent, disableAgent,
+  type AgentSummary, type CreateAgentInput, type UpdateAgentInput, type ListAgentsOptions,
+} from "./agents.ts";
+
+export {
+  createSkill, getSkill, listSkills, updateSkill, deleteSkill, toggleSkill,
+  importSkillFromDisk,
+  type SkillSummary, type CreateSkillInput, type UpdateSkillInput,
+} from "./skills.ts";
+
+export {
+  createCronJob, getCronJob, listCronJobs, updateCronJob, deleteCronJob,
+  pauseCronJob, resumeCronJob, triggerCronJob, getCronHistory, hasScheduler,
+  type CronJobSummary, type CreateCronInput, type UpdateCronInput,
+} from "./cron.ts";
+
+export {
+  listTools, getTool, toggleTool, updateToolMetadata,
+  type ToolSummary,
+} from "./tools.ts";
+
+export {
+  listEthics, getEthics, createEthics, updateEthics, toggleEthics, deleteEthics,
+  type EthicsSummary,
+} from "./ethics.ts";
+
+export {
+  listProviders, getProvider, createProvider, updateProvider, toggleProvider, deleteProvider,
+  type ProviderSummary,
+} from "./providers.ts";
+
+export {
+  listModels, getModel, createModel, toggleModel, deleteModel, renameModel, agentsUsingModel,
+  type ModelSummary,
+} from "./models.ts";
+
+export {
+  listMcpServers, getMcpServer, createMcpServer, updateMcpServer,
+  testMcpServer, toggleMcpServer, deleteMcpServer,
+  type McpServerSummary, type CreateMcpInput,
+} from "./mcp.ts";
+
+export {
+  createSwarm, getSwarm, listSwarms, updateSwarm, deleteSwarm, toggleSwarm, runSwarm,
+  type SwarmSummary, type SwarmMember, type CreateSwarmInput, type UpdateSwarmInput,
+  type RunSwarmOptions,
+} from "./swarms.ts";
+
+export {
+  createEndpoint, getEndpoint, listEndpoints, updateEndpoint, deleteEndpoint,
+  toggleEndpoint, testEndpoint, registerEndpointTools, buildEndpointTool, toolNameFor,
+  type EndpointSummary, type CreateEndpointInput,
+} from "./endpoints.ts";
+
+export {
+  planSeedFor, applySeedPlan, enableCatalogAgent, enableCatalogAgents,
+  disableCatalogAgent, listEnabledCatalogAgents, listCatalogPersonas,
+  planActivationFor, CATALOG_AGENT_IDS,
+  type SeedPlan, type ActivationGap,
+} from "./setup.ts";
+
+export {
+  uploadImage, transformStoredImage, getImageBytes, listImages,
+  setImageRetention, deleteImage, applyPreset, IMAGE_PRESETS,
+  type StoredImage, type TransformResult, type TransformSource,
+  type UploadOptions, type ServiceTransformOptions, type ImagePreset,
+} from "./images.ts";

package/packages/core/src/services/mcp.ts

@@ -0,0 +1,201 @@
+/**
+ * Servidores MCP — la API, no la ruta.
+ *
+ * Un servidor MCP es la vía real para que alguien sume capacidades propias sin
+ * escribir código dentro del SDK: levanta un proceso que expone tools por el
+ * protocolo, lo registra acá, y sus tools quedan disponibles para los agentes.
+ *
+ * Añade algo que hive no tiene: **`testMcpServer()`**. Allí probar un servidor
+ * consiste en crearlo, activarlo y esperar a que el hot-reload lo conecte (~2s)
+ * para ver si el estado quedó en `connected` o `error`. Para una UI eso es un
+ * "guardá y cruzá los dedos"; acá se puede intentar la conexión y responder si
+ * funcionó, sin dejar una fila a medio configurar.
+ *
+ * Las credenciales van cifradas por `storage/crypto.ts`: `headers` para los
+ * transportes HTTP, `env` para los de stdio. Nunca se devuelven en claro.
+ */
+
+import { col } from "../storage/hive.ts";
+import type { McpServerDoc } from "../storage/collections.ts";
+import {
+  storeMcpHeaders, loadMcpHeaders, storeMcpEnv, deleteMcpSecrets, maskApiKey,
+} from "../storage/crypto.ts";
+import { getMCPManager } from "../mcp/singleton.ts";
+import { slugify } from "./agents.ts";
+import { logger } from "../utils/logger.ts";
+
+const log = logger.child("services/mcp");
+
+export interface McpServerSummary {
+  id: string;
+  name: string;
+  transport: string;
+  command: string | null;
+  args: string[];
+  url: string | null;
+  enabled: boolean;
+  active: boolean;
+  builtin: boolean;
+  /** Estado en vivo si hay manager conectado; si no, el último persistido. */
+  status: string;
+  toolsCount: number;
+  /** Sólo qué cabeceras hay configuradas, con el valor enmascarado. */
+  maskedHeaders: Record<string, string>;
+}
+
+export interface CreateMcpInput {
+  name: string;
+  transport?: "stdio" | "http" | "sse";
+  command?: string | null;
+  args?: string[];
+  url?: string | null;
+  headers?: Record<string, string>;
+  env?: Record<string, string>;
+  enabled?: boolean;
+}
+
+function parseArgs(raw: string | null): string[] {
+  if (!raw) return [];
+  try {
+    const v = JSON.parse(raw);
+    return Array.isArray(v) ? v.map(String) : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Enmascara los valores: una UI necesita saber qué hay, no cuál es. */
+function maskHeaders(headers: Record<string, unknown>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) out[k] = maskApiKey(String(v));
+  return out;
+}
+
+async function mcpCol() {
+  return col<McpServerDoc>("mcpServers");
+}
+
+async function toSummary(doc: McpServerDoc): Promise<McpServerSummary> {
+  const headers = await loadMcpHeaders(doc.id).catch(() => ({}));
+  const manager = getMCPManager();
+  const live = manager?.getServerStatus?.(doc.name);
+  return {
+    id: doc.id,
+    name: doc.name,
+    transport: doc.transport,
+    command: doc.command,
+    args: parseArgs(doc.args),
+    url: doc.url,
+    enabled: doc.enabled,
+    active: doc.active,
+    builtin: doc.builtin,
+    status: live ?? doc.status,
+    toolsCount: doc.tools_count,
+    maskedHeaders: maskHeaders(headers as Record<string, unknown>),
+  };
+}
+
+export async function listMcpServers(opts?: { includeDisabled?: boolean }): Promise<McpServerSummary[]> {
+  const rows = await (await mcpCol()).scan({});
+  const docs = rows.map((e) => e.doc).filter((d) => (opts?.includeDisabled ? true : d.enabled));
+  return Promise.all(docs.map(toSummary));
+}
+
+export async function getMcpServer(id: string): Promise<McpServerSummary | null> {
+  const entry = await (await mcpCol()).get(id);
+  return entry ? toSummary(entry.doc) : null;
+}
+
+export async function createMcpServer(input: CreateMcpInput): Promise<McpServerSummary> {
+  if (!input.name?.trim()) throw new Error("El servidor MCP necesita un nombre");
+
+  const transport = input.transport ?? (input.url ? "http" : "stdio");
+  if (transport === "stdio" && !input.command) throw new Error("Un servidor stdio necesita `command`");
+  if (transport !== "stdio" && !input.url) throw new Error(`Un servidor ${transport} necesita \`url\``);
+
+  const c = await mcpCol();
+  const id = slugify(input.name).replace(/_/g, "-");
+  if (await c.get(id)) throw new Error(`Ya existe un servidor MCP con id "${id}"`);
+
+  const doc: McpServerDoc = {
+    id,
+    name: input.name,
+    transport,
+    command: input.command ?? null,
+    args: JSON.stringify(input.args ?? []),
+    url: input.url ?? null,
+    enabled: input.enabled ?? true,
+    active: false,
+    builtin: false,
+    status: "disconnected",
+    tools_count: 0,
+  };
+
+  await c.put(id, doc, { expectedVersion: 0 });
+  if (input.headers) await storeMcpHeaders(id, input.headers);
+  if (input.env) await storeMcpEnv(id, input.env);
+  log.info(`servidor MCP "${input.name}" registrado (${id})`);
+  return toSummary(doc);
+}
+
+export async function updateMcpServer(
+  id: string,
+  changes: Partial<CreateMcpInput>,
+): Promise<McpServerSummary> {
+  const c = await mcpCol();
+  const entry = await c.get(id);
+  if (!entry) throw new Error(`No existe el servidor MCP "${id}"`);
+
+  const doc: McpServerDoc = { ...entry.doc };
+  if (changes.name !== undefined) doc.name = changes.name;
+  if (changes.transport !== undefined) doc.transport = changes.transport;
+  if (changes.command !== undefined) doc.command = changes.command;
+  if (changes.args !== undefined) doc.args = JSON.stringify(changes.args);
+  if (changes.url !== undefined) doc.url = changes.url;
+  if (changes.enabled !== undefined) doc.enabled = changes.enabled;
+
+  await c.put(id, doc, { expectedVersion: entry.version });
+  if (changes.headers) await storeMcpHeaders(id, changes.headers);
+  if (changes.env) await storeMcpEnv(id, changes.env);
+  return toSummary(doc);
+}
+
+/**
+ * Intenta conectar el servidor y reporta el resultado.
+ *
+ * Requiere un `MCPClientManager` activo: sin él no hay quién hable el protocolo,
+ * y devolver "ok" sería mentir. Con manager, el estado que se devuelve es el
+ * real tras el intento, no el que estaba guardado.
+ */
+export async function testMcpServer(id: string): Promise<{ ok: boolean; status: string; toolsCount?: number; error?: string }> {
+  const entry = await (await mcpCol()).get(id);
+  if (!entry) throw new Error(`No existe el servidor MCP "${id}"`);
+
+  const manager = getMCPManager();
+  if (!manager) {
+    throw new Error("Probar un servidor MCP requiere un MCPClientManager activo");
+  }
+
+  try {
+    await manager.connectServer(entry.doc.name);
+    const status = manager.getServerStatus?.(entry.doc.name) ?? "unknown";
+    return { ok: status === "connected", status };
+  } catch (error) {
+    return { ok: false, status: "error", error: (error as Error).message };
+  }
+}
+
+export async function toggleMcpServer(id: string, enabled: boolean): Promise<McpServerSummary> {
+  return updateMcpServer(id, { enabled });
+}
+
+export async function deleteMcpServer(id: string): Promise<boolean> {
+  const c = await mcpCol();
+  const entry = await c.get(id);
+  if (!entry) return false;
+  if (entry.doc.builtin) throw new Error("Un servidor MCP incorporado no se puede borrar; desactívalo");
+
+  await c.delete(id);
+  await deleteMcpSecrets(id).catch(() => {});
+  return true;
+}

package/packages/core/src/services/memory.ts

@@ -0,0 +1,133 @@
+/**
+ * Memoria de largo plazo — la API, no la tool.
+ *
+ * Estas operaciones sólo existían dentro de `memoryWriteTool` y sus cuatro
+ * hermanas (`tools/agents/index.ts`), con argumentos con forma de LLM y
+ * respuestas escritas para un prompt. Una UI que quisiera listar o editar la
+ * memoria del usuario tenía que llamar `tool.execute({...})` y parsear prosa,
+ * o escribir consultas crudas contra HiveDB.
+ *
+ * Acá vive la implementación; las tools pasan a ser envoltorios que la llaman y
+ * traducen el resultado al formato que espera el modelo. Una implementación,
+ * dos consumidores.
+ *
+ * Estas funciones **lanzan** en vez de devolver `{ok:false}`: un error es un
+ * error, y quien construya una UI quiere un `try/catch`, no inspeccionar un
+ * campo. La traducción a `{ok:false, error}` la hace el envoltorio de la tool.
+ *
+ * **Cada memoria pertenece a un usuario.** La colección era global al proceso
+ * —coherente con hive, que es mono-usuario— pero eso no sirve para un runtime
+ * donde cada quien arma su colmena: dos usuarios no podían tener una memoria
+ * con el mismo título, y cualquiera veía la del otro. `userId` es opcional en la
+ * firma y se resuelve solo cuando no viene, para no romper a quien ya llamaba
+ * estas funciones.
+ */
+
+import { col } from "../storage/hive.ts";
+import type { MemoryDoc } from "../storage/collections.ts";
+import { resolveUserId } from "../storage/onboarding.ts";
+
+export interface MemoryEntry {
+  title: string;
+  content: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface MemorySearchHit {
+  title: string;
+  snippet: string;
+}
+
+const SNIPPET_CHARS = 200;
+
+/**
+ * `${userId}:${title}` — el título solo no alcanza como id en cuanto hay más de
+ * un usuario. Guardar dos veces el mismo título del mismo usuario actualiza; el
+ * de otro usuario es otra memoria.
+ */
+const memoryId = (userId: string, title: string) => `${userId}:${title}`;
+
+/** Sin userId explícito se resuelve el del contexto; `""` es el caso mono-usuario. */
+async function resolveOwner(userId?: string): Promise<string> {
+  if (userId) return userId;
+  return (await resolveUserId({}).catch(() => null)) ?? "";
+}
+
+function toEntry(doc: MemoryDoc): MemoryEntry {
+  return {
+    title: doc.title,
+    content: doc.content,
+    createdAt: doc.created_at,
+    updatedAt: doc.updated_at,
+  };
+}
+
+async function memoryCol() {
+  return col<MemoryDoc>("memory");
+}
+
+/** Guarda o actualiza una entrada. Devuelve la entrada resultante. */
+export async function writeMemory(title: string, content: string, userId?: string): Promise<MemoryEntry> {
+  if (!title.trim()) throw new Error("La memoria necesita un título");
+
+  const owner = await resolveOwner(userId);
+  const id = memoryId(owner, title);
+  const c = await memoryCol();
+  const existing = await c.get(id);
+  const now = Date.now();
+  const doc: MemoryDoc = {
+    id,
+    user_id: owner,
+    title,
+    content,
+    created_at: existing?.doc.created_at ?? now,
+    updated_at: now,
+  };
+  await c.put(id, doc, { expectedVersion: existing?.version ?? 0 });
+  return toEntry(doc);
+}
+
+/** La entrada, o null si no existe. */
+export async function readMemory(title: string, userId?: string): Promise<MemoryEntry | null> {
+  const owner = await resolveOwner(userId);
+  const entry = await (await memoryCol()).get(memoryId(owner, title));
+  return entry ? toEntry(entry.doc) : null;
+}
+
+/** Todas las entradas, de la más reciente a la más vieja. */
+export async function listMemories(userId?: string): Promise<MemoryEntry[]> {
+  const owner = await resolveOwner(userId);
+  const rows = await (await memoryCol()).findBy("user_id", owner);
+  return rows.map((e) => toEntry(e.doc)).sort((a, b) => b.updatedAt - a.updatedAt);
+}
+
+/**
+ * Búsqueda por subcadena en título y contenido.
+ *
+ * Deliberadamente simple: no pasa por el índice BM25 porque la memoria no se
+ * indexa ahí. Para colecciones grandes conviene revisarlo, pero cambiar el
+ * comportamiento ahora rompería lo que el modelo ya espera.
+ */
+export async function searchMemories(query: string, userId?: string): Promise<MemorySearchHit[]> {
+  const needle = query.toLowerCase();
+  const owner = await resolveOwner(userId);
+  const rows = await (await memoryCol()).findBy("user_id", owner);
+  return rows
+    .map((e) => e.doc)
+    .filter((n) => n.content.toLowerCase().includes(needle) || n.title.toLowerCase().includes(needle))
+    .map((n) => ({
+      title: n.title,
+      snippet: n.content.slice(0, SNIPPET_CHARS) + (n.content.length > SNIPPET_CHARS ? "..." : ""),
+    }));
+}
+
+/** Borra una entrada. `false` si no existía. */
+export async function deleteMemory(title: string, userId?: string): Promise<boolean> {
+  const owner = await resolveOwner(userId);
+  const id = memoryId(owner, title);
+  const c = await memoryCol();
+  if (!(await c.get(id))) return false;
+  await c.delete(id);
+  return true;
+}