@neo4j-labs/agent-memory 0.3.0

package/dist/index.js

@@ -0,0 +1,1313 @@
+import { extractRequestId, supportsUserAgentHeader, defaultUserAgent, BridgeTransport } from './chunk-TGBKROHO.js';
+export { VERSION } from './chunk-TGBKROHO.js';
+import { ConnectionError, AuthenticationError, NotSupportedError, TransportError, ValidationError } from './chunk-ASQMU7YC.js';
+export { AuthenticationError, ConnectionError, MemoryError, NotFoundError, NotSupportedError, TransportError, ValidationError } from './chunk-ASQMU7YC.js';
+
+// src/auth/index.ts
+function toApiKey(w) {
+  return {
+    id: w.id,
+    label: w.label,
+    scopes: w.scopes ?? [],
+    workspaceId: w.workspace_id,
+    createdAt: w.created_at,
+    expiresAt: w.expires_at,
+    key: w.key
+  };
+}
+var AuthClient = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  /** List API keys for a workspace (no plaintext). */
+  async listApiKeys(workspaceId) {
+    const wire = await this.transport.request("list_api_keys", {
+      workspace_id: workspaceId
+    });
+    return (wire ?? []).map(toApiKey);
+  }
+  /** Create a new API key. The plaintext value is returned only once. */
+  async createApiKey(input) {
+    const wire = await this.transport.request("create_api_key", {
+      label: input.label,
+      scopes: input.scopes,
+      workspace_id: input.workspaceId
+    });
+    return toApiKey(wire);
+  }
+  /** Revoke (delete) an API key by id. */
+  async revokeApiKey(keyId) {
+    await this.transport.request("revoke_api_key", { key_id: keyId });
+  }
+  /** Reveal the plaintext value of a stored API key. */
+  async revealApiKey(keyId, workspaceId) {
+    const wire = await this.transport.request("reveal_api_key", {
+      key_id: keyId,
+      workspace_id: workspaceId
+    });
+    return toApiKey(wire);
+  }
+  /** Exchange a refresh token for a fresh access/refresh pair. */
+  async refreshAccessToken(refreshToken) {
+    const wire = await this.transport.request("refresh_access_token", {
+      refresh_token: refreshToken
+    });
+    return {
+      accessToken: wire.access_token,
+      refreshToken: wire.refresh_token,
+      expiresIn: wire.expires_in
+    };
+  }
+};
+
+// src/long-term/index.ts
+function toEntity(w) {
+  return {
+    id: w.id,
+    name: w.name,
+    type: w.type,
+    subtype: w.subtype,
+    description: w.description,
+    embedding: w.embedding,
+    canonicalName: w.canonical_name,
+    createdAt: w.created_at ?? "",
+    updatedAt: w.updated_at,
+    confidence: w.confidence,
+    sourceStage: w.source_stage,
+    relationships: w.relationships?.map(toRelRef)
+  };
+}
+function toRelRef(w) {
+  return {
+    id: w.id,
+    type: w.type,
+    targetId: w.target_id,
+    targetName: w.target_name,
+    properties: w.properties
+  };
+}
+function toPreference(w) {
+  return {
+    id: w.id,
+    category: w.category,
+    preference: w.preference,
+    context: w.context,
+    embedding: w.embedding
+  };
+}
+function toFact(w) {
+  return {
+    id: w.id,
+    subject: w.subject,
+    predicate: w.predicate,
+    object: w.object,
+    embedding: w.embedding
+  };
+}
+function toRelationship(w) {
+  return {
+    id: w.id,
+    sourceId: w.source_id,
+    targetId: w.target_id,
+    relationshipType: w.relationship_type,
+    properties: w.properties ?? {}
+  };
+}
+function toMention(w) {
+  return {
+    conversationId: w.conversation_id,
+    messageId: w.message_id,
+    content: w.content,
+    timestamp: w.timestamp
+  };
+}
+function toGraphNode(w) {
+  return { id: w.id, name: w.name, type: w.type };
+}
+function toGraphEdge(w) {
+  return { id: w.id, source: w.source, target: w.target, type: w.type };
+}
+var LongTermMemory = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  // ---- Silver tier (bridge) ----------------------------------------------
+  async addEntity(name, entityType, options) {
+    const wire = await this.transport.request("add_entity", {
+      name,
+      entity_type: entityType,
+      type: entityType,
+      description: options?.description
+    });
+    return toEntity(wire);
+  }
+  async addPreference(category, preference, options) {
+    const wire = await this.transport.request("add_preference", {
+      category,
+      preference,
+      context: options?.context
+    });
+    return toPreference(wire);
+  }
+  async addFact(subject, predicate, obj) {
+    const wire = await this.transport.request("add_fact", {
+      subject,
+      predicate,
+      obj
+    });
+    return toFact(wire);
+  }
+  async searchEntities(query, options) {
+    const wire = await this.transport.request("search_entities", {
+      query,
+      type: options?.type,
+      limit: options?.limit ?? 10
+    });
+    return wire.map(toEntity);
+  }
+  async searchPreferences(query, options) {
+    const wire = await this.transport.request("search_preferences", {
+      query,
+      category: options?.category,
+      limit: options?.limit ?? 10
+    });
+    return wire.map(toPreference);
+  }
+  async getEntityByName(name) {
+    const wire = await this.transport.request("get_entity_by_name", {
+      name
+    });
+    return wire ? toEntity(wire) : null;
+  }
+  async getRelatedEntities(entityId, options) {
+    const wire = await this.transport.request("get_related_entities", {
+      entity_id: entityId,
+      relationship_type: options?.relationshipType,
+      depth: options?.depth ?? 1
+    });
+    return wire.map(toEntity);
+  }
+  async addRelationship(sourceId, targetId, relationshipType, options) {
+    const wire = await this.transport.request("add_relationship", {
+      source_id: sourceId,
+      target_id: targetId,
+      relationship_type: relationshipType,
+      properties: options?.properties
+    });
+    return toRelationship(wire);
+  }
+  async mergeDuplicateEntities(sourceId, targetId, options) {
+    const wire = await this.transport.request("merge_duplicate_entities", {
+      source_id: sourceId,
+      target_id: targetId,
+      canonical_name: options?.canonicalName
+    });
+    return toEntity(wire);
+  }
+  // ---- Volume 5 / hosted-native methods -----------------------------------
+  /** List all entities, optionally filtered by entity type. */
+  async listEntities(options) {
+    const wire = await this.transport.request("list_entities", {
+      type: options?.type,
+      limit: options?.limit
+    });
+    return wire.map(toEntity);
+  }
+  /** Fetch one entity (with relationships) by id. */
+  async getEntity(entityId) {
+    const wire = await this.transport.request("get_entity", {
+      entity_id: entityId
+    });
+    return toEntity(wire);
+  }
+  /** Update an existing entity's name and/or description.
+   *
+   * The hosted PUT /v1/entities/{id} returns `{status: "updated"}` rather
+   * than the full entity, so when the response lacks an `id` we follow up
+   * with a GET to keep the SDK contract — "update returns the updated
+   * Entity". Bridge transports return the entity directly, so we tolerate
+   * both shapes.
+   */
+  async updateEntity(entityId, options) {
+    const wire = await this.transport.request(
+      "update_entity",
+      {
+        entity_id: entityId,
+        name: options.name,
+        description: options.description
+      }
+    );
+    if (wire && typeof wire === "object" && "id" in wire && wire.id) {
+      return toEntity(wire);
+    }
+    return this.getEntity(entityId);
+  }
+  /** Delete an entity and its relationships. */
+  async deleteEntity(entityId) {
+    await this.transport.request("delete_entity", { entity_id: entityId });
+  }
+  /** Score an entity 0-1 and optionally mark it human-confirmed. */
+  async setEntityFeedback(entityId, options) {
+    const result = await this.transport.request(
+      "set_entity_feedback",
+      {
+        entity_id: entityId,
+        user_score: options.userScore,
+        confirmed: options.confirmed
+      }
+    );
+    return { id: result.id, updated: result.updated };
+  }
+  /** All cross-conversation mentions of this entity. */
+  async getEntityHistory(entityId) {
+    const wire = await this.transport.request("get_entity_history", {
+      entity_id: entityId
+    });
+    return {
+      entityId: wire.entity_id,
+      mentions: (wire.mentions ?? []).map(toMention)
+    };
+  }
+  /** Merge `sourceId` into `targetId`, leaving a SAME_AS provenance link. */
+  async mergeEntities(sourceId, targetId) {
+    const wire = await this.transport.request("merge_entities", {
+      source_id: sourceId,
+      target_id: targetId
+    });
+    return { sourceId: wire.source_id, targetId: wire.target_id, status: wire.status };
+  }
+  /** Full-graph view of all entities + edges. Pair with NVL for visualization. */
+  async getEntityGraph() {
+    const wire = await this.transport.request("get_entity_graph", {});
+    return {
+      nodes: (wire.nodes ?? []).map(toGraphNode),
+      edges: (wire.edges ?? []).map(toGraphEdge)
+    };
+  }
+};
+
+// src/query/index.ts
+var QueryConsole = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  /**
+   * Execute a read-only Cypher query.
+   *
+   * @example
+   * const r = await client.query.cypher({
+   *   cypher: "MATCH (e:Entity) RETURN e.name AS name LIMIT $n",
+   *   params: { n: 10 },
+   * });
+   */
+  async cypher(input) {
+    const wire = await this.transport.request("cypher_query", {
+      cypher: input.cypher,
+      params: input.params ?? {}
+    });
+    return {
+      columns: wire.columns ?? [],
+      rows: wire.rows ?? [],
+      stats: wire.stats
+    };
+  }
+};
+
+// src/reasoning/index.ts
+function toToolCall(w) {
+  return {
+    id: w.id,
+    toolName: w.tool_name ?? w.toolName ?? "",
+    arguments: w.arguments ?? (w.input ? safeParseObject(w.input) : {}) ?? {},
+    result: w.result ?? w.output,
+    status: w.status ?? "success",
+    durationMs: w.duration_ms ?? w.durationMs,
+    error: w.error
+  };
+}
+function safeParseObject(input) {
+  try {
+    const parsed = JSON.parse(input);
+    return typeof parsed === "object" && parsed !== null ? parsed : { value: parsed };
+  } catch {
+    return { raw: input };
+  }
+}
+function toStep(w) {
+  return {
+    id: w.id,
+    traceId: w.trace_id ?? "",
+    stepNumber: w.step_number ?? 0,
+    thought: w.thought,
+    action: w.action,
+    observation: w.observation,
+    toolCalls: (w.tool_calls ?? []).map(toToolCall)
+  };
+}
+function toTrace(w) {
+  return {
+    id: w.id,
+    sessionId: w.session_id ?? "",
+    task: w.task ?? "",
+    steps: (w.steps ?? []).map(toStep),
+    outcome: w.outcome,
+    success: w.success,
+    startedAt: w.started_at ?? "",
+    completedAt: w.completed_at
+  };
+}
+function toToolStats(w) {
+  return {
+    name: w.name,
+    totalCalls: w.total_calls,
+    successfulCalls: w.successful_calls,
+    failedCalls: w.failed_calls,
+    successRate: w.success_rate,
+    avgDurationMs: w.avg_duration_ms
+  };
+}
+function toAgentStep(w) {
+  return {
+    id: w.id,
+    conversationId: w.conversation_id,
+    reasoning: w.reasoning,
+    actionTaken: w.action_taken,
+    result: w.result,
+    createdAt: w.created_at ?? ""
+  };
+}
+var ReasoningMemory = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  // ---- Silver tier (bridge) ----------------------------------------------
+  async startTrace(sessionId, task) {
+    const wire = await this.transport.request("start_trace", {
+      session_id: sessionId,
+      task
+    });
+    return toTrace(wire);
+  }
+  async addStep(traceId, options) {
+    const wire = await this.transport.request("add_step", {
+      trace_id: traceId,
+      thought: options?.thought,
+      action: options?.action,
+      observation: options?.observation
+    });
+    return toStep(wire);
+  }
+  async recordToolCall(stepId, toolName, args, options) {
+    const wire = await this.transport.request("record_tool_call", {
+      step_id: stepId,
+      tool_name: toolName,
+      arguments: args,
+      input: typeof args === "string" ? args : JSON.stringify(args),
+      result: options?.result,
+      output: typeof options?.result === "string" ? options.result : void 0,
+      status: options?.status ?? "success",
+      duration_ms: options?.durationMs,
+      error: options?.error
+    });
+    return toToolCall(wire);
+  }
+  async completeTrace(traceId, options) {
+    const wire = await this.transport.request("complete_trace", {
+      trace_id: traceId,
+      outcome: options?.outcome,
+      success: options?.success
+    });
+    return toTrace(wire);
+  }
+  async getTraceWithSteps(traceId) {
+    const wire = await this.transport.request("get_trace_with_steps", {
+      trace_id: traceId
+    });
+    return wire ? toTrace(wire) : null;
+  }
+  async listTraces(options) {
+    const wire = await this.transport.request("list_traces", {
+      session_id: options?.sessionId,
+      limit: options?.limit ?? 100
+    });
+    return wire.map(toTrace);
+  }
+  async getToolStats(toolName) {
+    const wire = await this.transport.request("get_tool_stats", {
+      tool_name: toolName
+    });
+    return wire.map(toToolStats);
+  }
+  async getSimilarTraces(task, options) {
+    const wire = await this.transport.request("get_similar_traces", {
+      task,
+      limit: options?.limit ?? 5,
+      success_only: options?.successOnly ?? true
+    });
+    return wire.map(toTrace);
+  }
+  // ---- Volume 5 / hosted-native methods -----------------------------------
+  /** Record one reasoning step under a conversation (hosted REACT model). */
+  async recordStep(input) {
+    const wire = await this.transport.request("record_step", {
+      conversation_id: input.conversationId,
+      reasoning: input.reasoning,
+      action_taken: input.actionTaken,
+      result: input.result
+    });
+    return toAgentStep(wire);
+  }
+  /** List all reasoning steps for one conversation. */
+  async listSteps(conversationId) {
+    const wire = await this.transport.request("list_steps", {
+      conversation_id: conversationId
+    });
+    return wire.map(toAgentStep);
+  }
+  /** Detailed step explanation with tool calls and influenced entities. */
+  async explainStep(stepId) {
+    const wire = await this.transport.request("explain_step", {
+      step_id: stepId
+    });
+    return {
+      ...toAgentStep(wire),
+      toolCalls: (wire.tool_calls ?? []).map(toToolCall),
+      influencedEntities: (wire.influenced_entities ?? []).map((e) => ({
+        id: String(e["id"] ?? ""),
+        name: String(e["name"] ?? ""),
+        type: String(e["type"] ?? ""),
+        description: e["description"],
+        createdAt: String(e["created_at"] ?? "")
+      }))
+    };
+  }
+  /** Full reasoning trace for a conversation (steps + tool calls). */
+  async getTraceByConversation(conversationId) {
+    const wire = await this.transport.request(
+      "get_trace_by_conversation",
+      { conversation_id: conversationId }
+    );
+    return {
+      conversationId: wire.conversation_id,
+      steps: (wire.steps ?? []).map(toAgentStep),
+      toolCalls: (wire.tool_calls ?? []).map(toToolCall)
+    };
+  }
+  /** All reasoning steps that influenced an entity's creation.
+   *
+   * Hosted REST returns the chain under `provenance`; bridge / older
+   * responses use `steps`. Accept either.
+   */
+  async getEntityProvenance(entityId) {
+    const wire = await this.transport.request("get_entity_provenance", { entity_id: entityId });
+    const rawSteps = wire.steps ?? wire.provenance ?? [];
+    return {
+      entityId: wire.entity_id,
+      steps: rawSteps.map(toAgentStep)
+    };
+  }
+};
+
+// src/short-term/index.ts
+function toMessage(w) {
+  return {
+    id: w.id,
+    role: w.role ?? "user",
+    content: w.content,
+    timestamp: w.timestamp ?? w.created_at ?? "",
+    embedding: w.embedding,
+    metadata: w.metadata ?? {},
+    conversationId: w.conversation_id
+  };
+}
+function toConversation(w) {
+  return {
+    id: w.id,
+    sessionId: w.session_id ?? w.id,
+    messages: (w.messages ?? []).map(toMessage),
+    messageCount: w.message_count,
+    title: w.title,
+    createdAt: w.created_at ?? "",
+    updatedAt: w.updated_at,
+    workspaceId: w.workspace_id,
+    userId: w.user_id,
+    metadata: w.metadata
+  };
+}
+function toSessionInfo(w) {
+  return {
+    sessionId: w.session_id ?? w.id ?? "",
+    messageCount: w.message_count ?? 0,
+    createdAt: w.created_at,
+    updatedAt: w.updated_at
+  };
+}
+function toObservation(w) {
+  return {
+    id: w.id,
+    conversationId: w.conversation_id,
+    content: w.content,
+    windowStart: w.window_start,
+    windowEnd: w.window_end,
+    createdAt: w.created_at
+  };
+}
+function toReflection(w) {
+  return {
+    id: w.id,
+    conversationId: w.conversation_id,
+    content: w.content,
+    createdAt: w.created_at
+  };
+}
+var ShortTermMemory = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  // ---- Bronze tier (bridge) ----------------------------------------------
+  async addMessage(sessionId, role, content, options) {
+    const wire = await this.transport.request("add_message", {
+      session_id: sessionId,
+      role,
+      content,
+      metadata: options?.metadata
+    });
+    return toMessage(wire);
+  }
+  async getConversation(sessionId, options) {
+    const wire = await this.transport.request("get_conversation", {
+      session_id: sessionId,
+      limit: options?.limit
+    });
+    return toConversation(wire);
+  }
+  async searchMessages(query, options) {
+    const wire = await this.transport.request("search_messages", {
+      query,
+      session_id: options?.sessionId,
+      limit: options?.limit ?? 10,
+      threshold: options?.threshold ?? 0.7
+    });
+    return wire.map(toMessage);
+  }
+  async listSessions(options) {
+    const wire = await this.transport.request("list_sessions", {
+      limit: options?.limit ?? 100
+    });
+    return wire.map(toSessionInfo);
+  }
+  async deleteMessage(messageId) {
+    const result = await this.transport.request("delete_message", {
+      message_id: messageId
+    });
+    return result.deleted;
+  }
+  async clearSession(sessionId) {
+    await this.transport.request("clear_session", { session_id: sessionId });
+  }
+  // ---- Volume 5 / hosted-native methods -----------------------------------
+  /** Create a new conversation (hosted service). */
+  async createConversation(options) {
+    const wire = await this.transport.request("create_conversation", {
+      user_id: options.userId,
+      metadata: options.metadata
+    });
+    return toConversation(wire);
+  }
+  /** List conversations the API key has access to. */
+  async listConversations(options) {
+    const wire = await this.transport.request("list_conversations", {
+      limit: options?.limit,
+      userId: options?.userId
+    });
+    return wire.map(toConversation);
+  }
+  /** Fetch conversation metadata (no messages). */
+  async getConversationMetadata(conversationId) {
+    const wire = await this.transport.request("get_conversation_metadata", {
+      conversation_id: conversationId
+    });
+    return toConversation(wire);
+  }
+  /** Delete a conversation and all its messages. */
+  async deleteConversation(conversationId) {
+    await this.transport.request("delete_conversation", { conversation_id: conversationId });
+  }
+  /**
+   * Three-tier conversational context (reflections + observations + recent
+   * messages). The richest input you can hand an LLM about a conversation.
+   */
+  async getContext(conversationId) {
+    const wire = await this.transport.request("get_context", {
+      conversation_id: conversationId
+    });
+    return {
+      reflections: (wire.reflections ?? []).map(toReflection),
+      observations: (wire.observations ?? []).map(toObservation),
+      recentMessages: (wire.recent_messages ?? []).map(toMessage)
+    };
+  }
+  /** Bulk-add up to 100 messages in one request. */
+  async bulkAddMessages(conversationId, messages) {
+    if (messages.length > 100) {
+      throw new Error("bulkAddMessages accepts a maximum of 100 messages per call.");
+    }
+    const wire = await this.transport.request("bulk_add_messages", {
+      conversation_id: conversationId,
+      messages
+    });
+    return wire.map(toMessage);
+  }
+  /** Auto-generated message-window summaries. */
+  async getObservations(conversationId, options) {
+    const wire = await this.transport.request("get_observations", {
+      conversation_id: conversationId,
+      limit: options?.limit
+    });
+    return wire.map(toObservation);
+  }
+  /** Higher-level reflections derived from observations. */
+  async getReflections(conversationId) {
+    const wire = await this.transport.request("get_reflections", {
+      conversation_id: conversationId
+    });
+    return wire.map(toReflection);
+  }
+};
+
+// src/transport/casing.ts
+var SNAKE_RE = /_([a-z0-9])/g;
+var CAMEL_RE = /([A-Z])/g;
+function snakeKey(key) {
+  return key.replace(CAMEL_RE, (_, c) => `_${c.toLowerCase()}`);
+}
+function camelKey(key) {
+  return key.replace(SNAKE_RE, (_, c) => c.toUpperCase());
+}
+function snakeToCamel(value) {
+  if (Array.isArray(value)) {
+    return value.map((v) => snakeToCamel(v));
+  }
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[camelKey(k)] = snakeToCamel(v);
+    }
+    return out;
+  }
+  return value;
+}
+function camelToSnake(value) {
+  if (Array.isArray(value)) {
+    return value.map((v) => camelToSnake(v));
+  }
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[snakeKey(k)] = camelToSnake(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+// src/transport/rest.ts
+function trimTrailingSlashes(s) {
+  let end = s.length;
+  while (end > 0 && s.charCodeAt(end - 1) === 47) end--;
+  return s.slice(0, end);
+}
+function nowMs() {
+  if (typeof performance !== "undefined" && typeof performance.now === "function") {
+    return performance.now();
+  }
+  return Date.now();
+}
+function snakeToCamelKey(s) {
+  return s.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+var ROUTES = {
+  // Lifecycle ----------------------------------------------------------------
+  setup: "noop",
+  teardown: "noop",
+  // Hosted has no global clear; we delete every conversation owned by the API
+  // key. This is best-effort — see clearAllData() for the implementation.
+  clear_all_data: "noop",
+  // Short-Term — legacy bridge methods (mapped where a clean REST equivalent
+  // exists; bridge sessionId is treated as the conversationId UUID).
+  add_message: {
+    method: "POST",
+    path: "/conversations/{sessionId}/messages",
+    pathParams: ["sessionId"],
+    hasBody: true
+  },
+  get_conversation: {
+    method: "GET",
+    path: "/conversations/{sessionId}/messages",
+    pathParams: ["sessionId"],
+    queryParams: ["limit"],
+    shape: (raw, p) => {
+      const messages = raw?.messages ?? raw ?? [];
+      return {
+        id: p["sessionId"],
+        session_id: p["sessionId"],
+        messages,
+        created_at: null
+      };
+    }
+  },
+  list_sessions: {
+    method: "GET",
+    path: "/conversations",
+    queryParams: ["limit"],
+    shape: (raw) => {
+      const conversations = raw?.conversations ?? [];
+      return conversations.map((c) => {
+        const conv = c;
+        return {
+          session_id: conv["id"],
+          message_count: conv["messageCount"] ?? 0,
+          created_at: conv["createdAt"],
+          updated_at: conv["updatedAt"]
+        };
+      });
+    }
+  },
+  search_messages: {
+    method: "POST",
+    path: "/conversations/{sessionId}/search",
+    pathParams: ["sessionId"],
+    hasBody: true,
+    shape: (raw) => raw?.messages ?? []
+  },
+  clear_session: {
+    method: "DELETE",
+    path: "/conversations/{sessionId}",
+    pathParams: ["sessionId"]
+  },
+  delete_message: "unsupported",
+  // Long-Term — legacy mapped methods
+  add_entity: {
+    method: "POST",
+    path: "/entities",
+    hasBody: true
+  },
+  search_entities: {
+    method: "POST",
+    path: "/entities/search",
+    hasBody: true,
+    shape: (raw) => raw?.entities ?? []
+  },
+  add_preference: "unsupported",
+  add_fact: "unsupported",
+  search_preferences: "unsupported",
+  get_entity_by_name: "unsupported",
+  get_related_entities: "unsupported",
+  add_relationship: "unsupported",
+  merge_duplicate_entities: "unsupported",
+  // Reasoning — legacy not directly representable in REST
+  start_trace: "unsupported",
+  add_step: "unsupported",
+  record_tool_call: {
+    method: "POST",
+    path: "/reasoning/tool-calls",
+    hasBody: true
+  },
+  complete_trace: "unsupported",
+  get_trace_with_steps: "unsupported",
+  list_traces: "unsupported",
+  get_tool_stats: "unsupported",
+  get_similar_traces: "unsupported",
+  // ---- Hosted-native methods (Volume 5 / Platinum tier) --------------------
+  create_conversation: {
+    method: "POST",
+    path: "/conversations",
+    hasBody: true
+  },
+  list_conversations: {
+    method: "GET",
+    path: "/conversations",
+    queryParams: ["limit", "user_id"],
+    shape: (raw) => raw?.conversations ?? raw
+  },
+  get_conversation_metadata: {
+    method: "GET",
+    path: "/conversations/{conversationId}",
+    pathParams: ["conversationId"]
+  },
+  delete_conversation: {
+    method: "DELETE",
+    path: "/conversations/{conversationId}",
+    pathParams: ["conversationId"]
+  },
+  get_context: {
+    method: "GET",
+    path: "/conversations/{conversationId}/context",
+    pathParams: ["conversationId"]
+  },
+  bulk_add_messages: {
+    method: "POST",
+    path: "/conversations/{conversationId}/messages/bulk",
+    pathParams: ["conversationId"],
+    hasBody: true,
+    shape: (raw) => raw?.messages ?? raw
+  },
+  get_observations: {
+    method: "GET",
+    path: "/conversations/{conversationId}/observations",
+    pathParams: ["conversationId"],
+    queryParams: ["limit"],
+    shape: (raw) => raw?.observations ?? raw
+  },
+  get_reflections: {
+    method: "GET",
+    path: "/conversations/{conversationId}/reflections",
+    pathParams: ["conversationId"],
+    shape: (raw) => raw?.reflections ?? raw
+  },
+  list_entities: {
+    method: "GET",
+    path: "/entities",
+    queryParams: ["type", "limit"],
+    shape: (raw) => raw?.entities ?? raw
+  },
+  get_entity: {
+    method: "GET",
+    path: "/entities/{entityId}",
+    pathParams: ["entityId"]
+  },
+  update_entity: {
+    method: "PUT",
+    path: "/entities/{entityId}",
+    pathParams: ["entityId"],
+    hasBody: true
+  },
+  delete_entity: {
+    method: "DELETE",
+    path: "/entities/{entityId}",
+    pathParams: ["entityId"]
+  },
+  set_entity_feedback: {
+    method: "PUT",
+    path: "/entities/{entityId}/feedback",
+    pathParams: ["entityId"],
+    hasBody: true
+  },
+  get_entity_history: {
+    method: "GET",
+    path: "/entities/{entityId}/history",
+    pathParams: ["entityId"]
+  },
+  merge_entities: {
+    method: "POST",
+    path: "/entities/{sourceId}/merge",
+    pathParams: ["sourceId"],
+    hasBody: true
+  },
+  get_entity_graph: {
+    method: "GET",
+    path: "/entities/graph"
+  },
+  explain_step: {
+    method: "GET",
+    path: "/reasoning/explain/{stepId}",
+    pathParams: ["stepId"]
+  },
+  get_trace_by_conversation: {
+    method: "GET",
+    path: "/reasoning/trace/{conversationId}",
+    pathParams: ["conversationId"]
+  },
+  get_entity_provenance: {
+    method: "GET",
+    path: "/reasoning/provenance/{entityId}",
+    pathParams: ["entityId"]
+  },
+  record_step: {
+    method: "POST",
+    path: "/reasoning/steps",
+    hasBody: true
+  },
+  list_steps: {
+    method: "GET",
+    path: "/reasoning/steps",
+    queryParams: ["conversation_id"],
+    shape: (raw) => raw?.steps ?? raw
+  },
+  cypher_query: {
+    method: "POST",
+    path: "/query",
+    hasBody: true
+  },
+  // Auth
+  list_api_keys: {
+    method: "GET",
+    path: "/auth/api-keys",
+    queryParams: ["workspace_id"],
+    shape: (raw) => {
+      const r = raw;
+      return r?.keys ?? r?.api_keys ?? raw;
+    }
+  },
+  create_api_key: {
+    method: "POST",
+    path: "/auth/api-keys",
+    hasBody: true
+  },
+  revoke_api_key: {
+    method: "DELETE",
+    path: "/auth/api-keys/{keyId}",
+    pathParams: ["keyId"]
+  },
+  reveal_api_key: {
+    method: "GET",
+    path: "/auth/api-keys/{keyId}/reveal",
+    pathParams: ["keyId"],
+    queryParams: ["workspace_id"]
+  },
+  refresh_access_token: {
+    method: "POST",
+    path: "/auth/refresh",
+    hasBody: true
+  }
+};
+var RestTransport = class {
+  endpoint;
+  apiKey;
+  tokenProvider;
+  timeout;
+  headers;
+  logger;
+  constructor(options) {
+    this.endpoint = trimTrailingSlashes(options.endpoint);
+    this.apiKey = options.apiKey;
+    this.tokenProvider = options.tokenProvider;
+    this.timeout = options.timeout ?? 3e4;
+    this.headers = options.headers ?? {};
+    this.logger = options.logger;
+  }
+  async connect() {
+    const url = `${this.endpoint}/conversations?limit=1`;
+    const start = nowMs();
+    this.emit({ kind: "request", method: "connect", url, httpMethod: "GET" });
+    let response;
+    try {
+      response = await fetch(url, {
+        method: "GET",
+        headers: await this.buildHeaders(),
+        signal: AbortSignal.timeout(this.timeout)
+      });
+    } catch (error) {
+      const durationMs2 = nowMs() - start;
+      if (error instanceof TypeError) {
+        const err = new ConnectionError(
+          `Failed to connect to ${this.endpoint}: ${error.message}`,
+          { cause: error }
+        );
+        this.emit({ kind: "error", method: "connect", url, durationMs: durationMs2, message: err.message });
+        throw err;
+      }
+      if (error instanceof DOMException && error.name === "TimeoutError") {
+        const err = new ConnectionError(
+          `Connection to ${this.endpoint} timed out after ${this.timeout}ms`,
+          { cause: error }
+        );
+        this.emit({ kind: "error", method: "connect", url, durationMs: durationMs2, message: err.message });
+        throw err;
+      }
+      throw error;
+    }
+    const durationMs = nowMs() - start;
+    const requestId = extractRequestId(response.headers);
+    if (response.status === 401 || response.status === 403) {
+      const err = new AuthenticationError(
+        `Authentication failed against ${this.endpoint}: ${response.status} ${response.statusText}`,
+        { requestId }
+      );
+      this.emit({
+        kind: "error",
+        method: "connect",
+        url,
+        status: response.status,
+        requestId,
+        durationMs,
+        message: err.message
+      });
+      throw err;
+    }
+    if (!response.ok && response.status >= 500) {
+      const err = new ConnectionError(
+        `Server error from ${this.endpoint}: ${response.status} ${response.statusText}`,
+        { requestId }
+      );
+      this.emit({
+        kind: "error",
+        method: "connect",
+        url,
+        status: response.status,
+        requestId,
+        durationMs,
+        message: err.message
+      });
+      throw err;
+    }
+    this.emit({
+      kind: "response",
+      method: "connect",
+      url,
+      status: response.status,
+      requestId,
+      durationMs
+    });
+  }
+  async close() {
+  }
+  async request(method, params) {
+    const route = ROUTES[method];
+    if (!route) {
+      throw new NotSupportedError(
+        `Method '${method}' is not implemented by RestTransport. Use BridgeTransport for full TCK conformance, or call a hosted-native method.`
+      );
+    }
+    if (route === "noop") return void 0;
+    if (route === "unsupported") {
+      throw new NotSupportedError(
+        `Method '${method}' has no equivalent in the hosted Neo4j Agent Memory REST API. It is supported by BridgeTransport only.`
+      );
+    }
+    const original = params ?? {};
+    const camelParams = snakeToCamel(original);
+    let path = route.path;
+    const consumed = /* @__PURE__ */ new Set();
+    for (const name of route.pathParams ?? []) {
+      const v = camelParams[name];
+      if (v === void 0 || v === null || v === "") {
+        throw new TransportError(
+          `Missing required path parameter '${name}' for method '${method}'`,
+          400,
+          camelParams
+        );
+      }
+      path = path.replace(`{${name}}`, encodeURIComponent(String(v)));
+      consumed.add(name);
+    }
+    const queryEntries = [];
+    for (const name of route.queryParams ?? []) {
+      let v = original[name];
+      if (v === void 0 || v === null) {
+        const camel = snakeToCamelKey(name);
+        v = camelParams[camel];
+      }
+      if (v !== void 0 && v !== null) {
+        queryEntries.push([name, String(v)]);
+        consumed.add(name);
+        consumed.add(snakeToCamelKey(name));
+      }
+    }
+    const query = queryEntries.length ? "?" + queryEntries.map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join("&") : "";
+    let body;
+    if (route.hasBody) {
+      const bodyObj = {};
+      for (const [k, v] of Object.entries(camelParams)) {
+        if (!consumed.has(k) && v !== void 0 && v !== null) {
+          bodyObj[k] = v;
+        }
+      }
+      body = JSON.stringify(bodyObj);
+    }
+    const url = `${this.endpoint}${path}${query}`;
+    const start = nowMs();
+    this.emit({ kind: "request", method, url, httpMethod: route.method });
+    let response;
+    try {
+      response = await fetch(url, {
+        method: route.method,
+        headers: await this.buildHeaders(route.hasBody),
+        body,
+        signal: AbortSignal.timeout(this.timeout)
+      });
+    } catch (error) {
+      const durationMs2 = nowMs() - start;
+      if (error instanceof TypeError) {
+        const err = new ConnectionError(
+          `Request to ${url} failed: ${error.message}`,
+          { cause: error }
+        );
+        this.emit({ kind: "error", method, url, durationMs: durationMs2, message: err.message });
+        throw err;
+      }
+      throw error;
+    }
+    const requestId = extractRequestId(response.headers);
+    const durationMs = nowMs() - start;
+    if (response.status === 401 || response.status === 403) {
+      const err = new AuthenticationError(
+        `Authentication failed: ${response.status} ${response.statusText}`,
+        { requestId }
+      );
+      this.emit({
+        kind: "error",
+        method,
+        url,
+        status: response.status,
+        requestId,
+        durationMs,
+        message: err.message
+      });
+      throw err;
+    }
+    if (response.status === 204) {
+      this.emit({ kind: "response", method, url, status: 204, requestId, durationMs });
+      return void 0;
+    }
+    const text = await response.text();
+    if (!response.ok) {
+      let errorBody;
+      try {
+        errorBody = JSON.parse(text);
+      } catch {
+        errorBody = text;
+      }
+      const errMsg = typeof errorBody === "object" && errorBody !== null && "error" in errorBody ? String(errorBody["error"]) : `HTTP ${response.status}`;
+      const err = new TransportError(
+        `${method} failed: ${errMsg}`,
+        response.status,
+        errorBody,
+        { requestId }
+      );
+      this.emit({
+        kind: "error",
+        method,
+        url,
+        status: response.status,
+        requestId,
+        durationMs,
+        message: err.message
+      });
+      throw err;
+    }
+    this.emit({ kind: "response", method, url, status: response.status, requestId, durationMs });
+    if (!text) return void 0;
+    let parsed = JSON.parse(text);
+    if (route.shape) parsed = route.shape(parsed, camelParams);
+    return camelToSnake(parsed);
+  }
+  emit(event) {
+    if (!this.logger) return;
+    try {
+      this.logger(event);
+    } catch {
+    }
+  }
+  async buildHeaders(includeContentType = false) {
+    const headers = {};
+    const canSendUserAgent = supportsUserAgentHeader();
+    for (const [key, value] of Object.entries(this.headers)) {
+      if (key.toLowerCase() === "user-agent" && !canSendUserAgent) continue;
+      headers[key] = value;
+    }
+    if (canSendUserAgent && !Object.keys(headers).some((key) => key.toLowerCase() === "user-agent")) {
+      headers["User-Agent"] = defaultUserAgent();
+    }
+    if (includeContentType) headers["Content-Type"] = "application/json";
+    const token = this.tokenProvider ? await this.tokenProvider() : this.apiKey;
+    if (token) headers["Authorization"] = `Bearer ${token}`;
+    return headers;
+  }
+};
+
+// src/client.ts
+var DEFAULT_ENDPOINT = "https://memory.neo4jlabs.com/v1";
+var MemoryClient = class {
+  /** Short-term (conversational) memory operations. */
+  shortTerm;
+  /** Long-term (entity / preference / fact / graph) memory operations. */
+  longTerm;
+  /** Reasoning (trace / step / tool call / provenance) memory operations. */
+  reasoning;
+  /** Read-only Cypher query console (hosted service only). */
+  query;
+  /** API-key & OAuth management (hosted service only). */
+  auth;
+  transport;
+  constructor(optionsOrTransport = {}) {
+    if (isTransport(optionsOrTransport)) {
+      this.transport = optionsOrTransport;
+    } else {
+      this.transport = new LazyConnectTransport(createTransport(optionsOrTransport));
+    }
+    this.shortTerm = new ShortTermMemory(this.transport);
+    this.longTerm = new LongTermMemory(this.transport);
+    this.reasoning = new ReasoningMemory(this.transport);
+    this.query = new QueryConsole(this.transport);
+    this.auth = new AuthClient(this.transport);
+  }
+  async connect() {
+    await this.transport.connect();
+  }
+  async close() {
+    await this.transport.close();
+  }
+};
+function isTransport(obj) {
+  return typeof obj === "object" && obj !== null && "request" in obj && typeof obj.request === "function";
+}
+function pickTransport(endpoint, mode) {
+  if (mode === "bridge" || mode === "rest") return mode;
+  return /\/v\d+\b/.test(endpoint) ? "rest" : "bridge";
+}
+function resolveApiKey(option) {
+  if (option !== void 0) return option;
+  if (typeof process === "undefined" || !process.env) return void 0;
+  return process.env.MEMORY_API_KEY;
+}
+function createTransport(options) {
+  const endpoint = options.endpoint;
+  const apiKey = resolveApiKey(options.apiKey);
+  const choice = pickTransport(endpoint ?? DEFAULT_ENDPOINT, options.transport);
+  if (choice === "rest") {
+    return new RestTransport({
+      endpoint: endpoint ?? DEFAULT_ENDPOINT,
+      apiKey,
+      tokenProvider: options.tokenProvider,
+      timeout: options.timeout,
+      headers: options.headers,
+      logger: options.logger
+    });
+  }
+  if (!endpoint) {
+    throw new ValidationError("endpoint must be provided for bridge transport.");
+  }
+  return new BridgeTransport({
+    endpoint,
+    apiKey,
+    timeout: options.timeout,
+    headers: options.headers,
+    logger: options.logger
+  });
+}
+var LazyConnectTransport = class {
+  constructor(inner) {
+    this.inner = inner;
+  }
+  connectPromise = null;
+  async request(method, params) {
+    return this.inner.request(method, params);
+  }
+  async connect() {
+    if (!this.connectPromise) {
+      this.connectPromise = this.inner.connect().catch((err) => {
+        this.connectPromise = null;
+        throw err;
+      });
+    }
+    return this.connectPromise;
+  }
+  async close() {
+    return this.inner.close();
+  }
+};
+
+export { AuthClient, LongTermMemory, MemoryClient, QueryConsole, ReasoningMemory, RestTransport, ShortTermMemory };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map