@neo4j-labs/agent-memory 0.3.0

package/dist/middleware/vercel-ai.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/middleware/vercel-ai.ts"],"names":[],"mappings":";;;AAqFA,SAAS,QAAQ,KAAA,EAAqD;AACpE,EAAA,IAAI,OAAO,KAAA,KAAU,UAAA,EAAY,OAAO,KAAA,EAAM;AAC9C,EAAA,OAAO,KAAA;AACT;AAGO,SAAS,qBAAA,CACd,QACA,OAAA,EACoC;AACpC,EAAA,MAAM,gBAAA,GAAmB,SAAS,gBAAA,IAAoB,IAAA;AACtD,EAAA,MAAM,YAAA,GAAe,SAAS,YAAA,IAAgB,IAAA;AAC9C,EAAA,MAAM,cAAA,GAAiB,SAAS,cAAA,IAAkB,IAAA;AAClD,EAAA,IAAI,aACF,OAAA,CAAQ,OAAA,EAAS,cAAc,CAAA,IAAK,OAAA,CAAQ,SAAS,SAAS,CAAA;AAGhE,EAAA,eAAe,oBAAA,GAAwC;AACrD,IAAA,IAAI,YAAY,OAAO,UAAA;AACvB,IAAA,IAAI;AACF,MAAA,MAAM,IAAA,GAAO,MAAM,MAAA,CAAO,SAAA,CAAU,kBAAA,CAAmB;AAAA,QACrD,MAAA,EAAQ,SAAS,MAAA,IAAU;AAAA,OAC5B,CAAA;AACD,MAAA,UAAA,GAAa,IAAA,CAAK,EAAA;AAClB,MAAA,OAAO,UAAA;AAAA,IACT,SAAS,GAAA,EAAK;AACZ,MAAA,IAAI,eAAe,iBAAA,EAAmB;AAEpC,QAAA,UAAA,GAAa,CAAA,QAAA,EAAW,cAAc,CAAA,CAAA;AACtC,QAAA,OAAO,UAAA;AAAA,MACT;AACA,MAAA,MAAM,GAAA;AAAA,IACR;AAAA,EACF;AAEA,EAAA,OAAO;AAAA,IACL,eAAA,EAAiB,OAAO,EAAE,MAAA,EAAO,KAAM;AACrC,MAAA,MAAM,EAAA,GAAK,MAAM,oBAAA,EAAqB;AAEtC,MAAA,IAAI,kBAA4D,EAAC;AACjE,MAAA,IAAI,cAAA,EAAgB;AAClB,QAAA,IAAI;AACF,UAAA,MAAM,GAAA,GAAM,MAAM,MAAA,CAAO,SAAA,CAAU,WAAW,EAAE,CAAA;AAChD,UAAA,KAAA,MAAW,CAAA,IAAK,IAAI,WAAA,EAAa;AAC/B,YAAA,eAAA,CAAgB,IAAA,CAAK,EAAE,IAAA,EAAM,QAAA,EAAU,SAAS,CAAA,aAAA,EAAgB,CAAA,CAAE,OAAO,CAAA,CAAA,EAAI,CAAA;AAAA,UAC/E;AACA,UAAA,KAAA,MAAW,CAAA,IAAK,IAAI,YAAA,EAAc;AAChC,YAAA,eAAA,CAAgB,IAAA,CAAK,EAAE,IAAA,EAAM,QAAA,EAAU,SAAS,CAAA,cAAA,EAAiB,CAAA,CAAE,OAAO,CAAA,CAAA,EAAI,CAAA;AAAA,UAChF;AACA,UAAA,KAAA,MAAW,CAAA,IAAK,IAAI,cAAA,EAAgB;AAClC,YAAA,eAAA,CAAgB,IAAA,CAAK,EAAE,IAAA,EAAM,CAAA,CAAE,MAAM,OAAA,EAAS,CAAA,CAAE,SAAS,CAAA;AAAA,UAC3D;AAAA,QACF,SAAS,GAAA,EAAK;AAIZ,UAAA,eAAA,GAAkB,EAAC;AAAA,QACrB;AAAA,MACF;AAGA,MAAA,IAAI,eAAA,CAAgB,WAAW,CAAA,EAAG;AAChC,QAAA,IAAI;AACF,UAAA,MAAM,IAAA,GAAO,MAAM,MAAA,CAAO,SAAA,CAAU,gBAAgB,EAAA,EAAI;AAAA,YACtD,OAAO,OAAA,EAAS;AAAA,WACjB,CAAA;AACD,UAAA,eAAA,GAAkB,IAAA,CAAK,QAAA,CAAS,GAAA,CAAI,CAAC,GAAA,MAAkB;AAAA,YACrD,MAAM,GAAA,CAAI,IAAA;AAAA,YACV,SAAS,GAAA,CAAI;AAAA,WACf,CAAE,CAAA;AAAA,QACJ,CAAA,CAAA,MAAQ;AAAA,QAER;AAAA,MACF;AAGA,MAAA,IAAI,YAAA,EAAc;AAChB,QAAA,MAAM,QAAA,GAAY,MAAA,CAAO,QAAQ,CAAA,IAAkD,EAAC;AACpF,QAAA,MAAM,QAAA,GAAW,CAAC,GAAG,QAAQ,CAAA,CAAE,OAAA,EAAQ,CAAE,IAAA,CAAK,CAAC,CAAA,KAAM,CAAA,CAAE,IAAA,KAAS,MAAM,CAAA;AACtE,QAAA,IAAI,QAAA,EAAU;AACZ,UAAA,IAAI;AACF,YAAA,MAAM,OAAO,SAAA,CAAU,UAAA,CAAW,IAAI,QAAA,CAAS,IAAA,EAAqB,SAAS,OAAO,CAAA;AAAA,UACtF,CAAA,CAAA,MAAQ;AAAA,UAER;AAAA,QACF;AAAA,MACF;AAEA,MAAA,IAAI,eAAA,CAAgB,MAAA,KAAW,CAAA,EAAG,OAAO,MAAA;AAEzC,MAAA,MAAM,QAAA,GAAY,MAAA,CAAO,QAAQ,CAAA,IAAmB,EAAC;AACrD,MAAA,OAAO;AAAA,QACL,GAAG,MAAA;AAAA,QACH,MAAA,EAAQ,CAAC,GAAG,eAAA,EAAiB,GAAG,QAAQ;AAAA,OAC1C;AAAA,IACF,CAAA;AAAA,IAEA,YAAA,EAAc,OAAO,EAAE,UAAA,EAAW,KAAM;AACtC,MAAA,MAAM,MAAA,GAAS,MAAM,UAAA,EAAW;AAChC,MAAA,IAAI,gBAAA,IAAoB,OAAO,IAAA,EAAM;AACnC,QAAA,MAAM,EAAA,GAAK,MAAM,oBAAA,EAAqB;AACtC,QAAA,IAAI;AACF,UAAA,MAAM,OAAO,SAAA,CAAU,UAAA,CAAW,EAAA,EAAI,WAAA,EAAa,OAAO,IAAI,CAAA;AAAA,QAChE,CAAA,CAAA,MAAQ;AAAA,QAER;AAAA,MACF;AACA,MAAA,OAAO,MAAA;AAAA,IACT;AAAA,GACF;AACF;AAEA,SAAS,YAAA,GAAuB;AAK9B,EAAA,IAAI,OAAO,MAAA,KAAW,WAAA,IAAe,OAAO,MAAA,CAAO,eAAe,UAAA,EAAY;AAC5E,IAAA,OAAO,OAAO,UAAA,EAAW;AAAA,EAC3B;AACA,EAAA,IAAI,OAAO,MAAA,KAAW,WAAA,IAAe,OAAO,MAAA,CAAO,oBAAoB,UAAA,EAAY;AACjF,IAAA,MAAM,GAAA,GAAM,IAAI,UAAA,CAAW,EAAE,CAAA;AAC7B,IAAA,MAAA,CAAO,gBAAgB,GAAG,CAAA;AAC1B,IAAA,OAAO,KAAA,CAAM,IAAA,CAAK,GAAA,EAAK,CAAC,MAAM,CAAA,CAAE,QAAA,CAAS,EAAE,CAAA,CAAE,SAAS,CAAA,EAAG,GAAG,CAAC,CAAA,CAAE,KAAK,EAAE,CAAA;AAAA,EACxE;AACA,EAAA,MAAM,IAAI,KAAA;AAAA,IACR;AAAA,GACF;AACF","file":"vercel-ai.js","sourcesContent":["/**\n * Vercel AI SDK middleware for automatic memory integration.\n *\n * The middleware automatically:\n *   - Injects three-tier conversational context (reflections + observations +\n *     recent messages) ahead of every model call when a `conversationId` is\n *     supplied — falls back to flat history for bridge transports.\n *   - Persists the user's input message before generation.\n *   - Persists the assistant's response (and tool calls) after generation.\n *   - Lazily creates a conversation on first call when the caller didn't\n *     pre-create one (only available with RestTransport).\n *\n * @example\n * ```ts\n * import { generateText } from \"ai\";\n * import { MemoryClient } from \"@neo4j-labs/agent-memory\";\n * import { agentMemoryMiddleware } from \"@neo4j-labs/agent-memory/middleware/vercel-ai\";\n *\n * const client = new MemoryClient({\n *   endpoint: \"https://memory.neo4jlabs.com/v1\",\n *   apiKey: process.env.MEMORY_API_KEY!,\n * });\n *\n * const middleware = agentMemoryMiddleware(client, {\n *   conversationId: \"conv-uuid\",      // or sessionId for bridge transport\n *   userId: \"alice@example.com\",      // used if a conversation is created\n *   includeContext: true,\n * });\n *\n * const result = await generateText({\n *   model: yourModel,\n *   experimental_middleware: middleware,\n *   messages: [{ role: \"user\", content: \"Hello!\" }],\n * });\n * ```\n *\n * Compatible with the Vercel AI SDK v4+ `LanguageModelV1Middleware` shape.\n */\n\nimport type { MemoryClient } from \"../client.js\";\nimport { NotSupportedError } from \"../errors.js\";\nimport type { Message, MessageRole } from \"../types.js\";\n\nexport interface AgentMemoryMiddlewareOptions {\n  /**\n   * Conversation id (REST transport) or session id (bridge transport).\n   * Can be a string or a function that returns one.\n   */\n  conversationId?: string | (() => string);\n\n  /** @deprecated Use `conversationId`. Kept for backwards compatibility. */\n  sessionId?: string | (() => string);\n\n  /**\n   * User id used when lazily creating a conversation. Only consulted if\n   * `conversationId` is not supplied and the transport is REST.\n   */\n  userId?: string;\n\n  /**\n   * Include three-tier context (reflections + observations + recent messages).\n   * If false, falls back to flat history. Default: true on REST, false on\n   * bridge (where context endpoints aren't implemented).\n   */\n  includeContext?: boolean;\n\n  /** Maximum messages to include from flat history (bridge fallback). */\n  historyLimit?: number;\n\n  /** Persist user input before generation. Default: true. */\n  persistInput?: boolean;\n\n  /** Persist assistant response after generation. Default: true. */\n  persistResponses?: boolean;\n}\n\nexport interface AgentMemoryLanguageModelMiddleware {\n  transformParams?: (options: { params: Record<string, unknown> }) => Promise<\n    Record<string, unknown>\n  >;\n  wrapGenerate?: (options: {\n    doGenerate: () => Promise<{ text?: string; [key: string]: unknown }>;\n  }) => Promise<{ text?: string; [key: string]: unknown }>;\n}\n\nfunction resolve(value?: string | (() => string)): string | undefined {\n  if (typeof value === \"function\") return value();\n  return value;\n}\n\n/** Memory-augmented LanguageModelV1 middleware. */\nexport function agentMemoryMiddleware(\n  client: MemoryClient,\n  options?: AgentMemoryMiddlewareOptions,\n): AgentMemoryLanguageModelMiddleware {\n  const persistResponses = options?.persistResponses ?? true;\n  const persistInput = options?.persistInput ?? true;\n  const includeContext = options?.includeContext ?? true;\n  let resolvedId: string | undefined =\n    resolve(options?.conversationId) ?? resolve(options?.sessionId);\n\n  // Lazy-create a conversation on REST transports if none was supplied.\n  async function ensureConversationId(): Promise<string> {\n    if (resolvedId) return resolvedId;\n    try {\n      const conv = await client.shortTerm.createConversation({\n        userId: options?.userId ?? \"anonymous\",\n      });\n      resolvedId = conv.id;\n      return resolvedId;\n    } catch (err) {\n      if (err instanceof NotSupportedError) {\n        // Bridge transport — synthesize a session ID\n        resolvedId = `session-${cryptoRandom()}`;\n        return resolvedId;\n      }\n      throw err;\n    }\n  }\n\n  return {\n    transformParams: async ({ params }) => {\n      const id = await ensureConversationId();\n\n      let historyMessages: Array<{ role: string; content: string }> = [];\n      if (includeContext) {\n        try {\n          const ctx = await client.shortTerm.getContext(id);\n          for (const r of ctx.reflections) {\n            historyMessages.push({ role: \"system\", content: `[reflection] ${r.content}` });\n          }\n          for (const o of ctx.observations) {\n            historyMessages.push({ role: \"system\", content: `[observation] ${o.content}` });\n          }\n          for (const m of ctx.recentMessages) {\n            historyMessages.push({ role: m.role, content: m.content });\n          }\n        } catch (err) {\n          if (!(err instanceof NotSupportedError)) {\n            // Non-fatal — fall back to flat history below.\n          }\n          historyMessages = [];\n        }\n      }\n\n      // Bridge fallback or empty REST context → use flat conversation history.\n      if (historyMessages.length === 0) {\n        try {\n          const conv = await client.shortTerm.getConversation(id, {\n            limit: options?.historyLimit,\n          });\n          historyMessages = conv.messages.map((msg: Message) => ({\n            role: msg.role,\n            content: msg.content,\n          }));\n        } catch {\n          // No history — proceed without.\n        }\n      }\n\n      // Best-effort: persist the user's input message.\n      if (persistInput) {\n        const incoming = (params[\"prompt\"] as Array<{ role: string; content: string }>) ?? [];\n        const lastUser = [...incoming].reverse().find((m) => m.role === \"user\");\n        if (lastUser) {\n          try {\n            await client.shortTerm.addMessage(id, lastUser.role as MessageRole, lastUser.content);\n          } catch {\n            // Non-fatal.\n          }\n        }\n      }\n\n      if (historyMessages.length === 0) return params;\n\n      const existing = (params[\"prompt\"] as unknown[]) ?? [];\n      return {\n        ...params,\n        prompt: [...historyMessages, ...existing],\n      };\n    },\n\n    wrapGenerate: async ({ doGenerate }) => {\n      const result = await doGenerate();\n      if (persistResponses && result.text) {\n        const id = await ensureConversationId();\n        try {\n          await client.shortTerm.addMessage(id, \"assistant\", result.text);\n        } catch {\n          // Non-fatal.\n        }\n      }\n      return result;\n    },\n  };\n}\n\nfunction cryptoRandom(): string {\n  // Every supported runtime (Node 20+, Bun, Deno, Workers, modern browsers)\n  // exposes crypto.randomUUID. We fall back to crypto.getRandomValues with\n  // base36 encoding for older or stripped-down environments — both APIs use\n  // the platform CSPRNG. Math.random would be cryptographically insecure.\n  if (typeof crypto !== \"undefined\" && typeof crypto.randomUUID === \"function\") {\n    return crypto.randomUUID();\n  }\n  if (typeof crypto !== \"undefined\" && typeof crypto.getRandomValues === \"function\") {\n    const buf = new Uint8Array(16);\n    crypto.getRandomValues(buf);\n    return Array.from(buf, (b) => b.toString(16).padStart(2, \"0\")).join(\"\");\n  }\n  throw new Error(\n    \"Secure randomness is unavailable in this runtime; supply an explicit conversationId.\",\n  );\n}\n"]}

package/dist/testing.d.ts

@@ -0,0 +1,37 @@
+import { T as Transport, L as Logger } from './index-qfRrdQNP.js';
+
+/**
+ * BridgeTransport — TCK bridge protocol transport.
+ *
+ * Speaks the bridge wire format (POST {endpoint}/{snake_case_method}) used by
+ * conformance servers and the local reference adapter. Compatible with every
+ * fetch-capable runtime (Node 20+, Bun, Deno, Workers, Edge).
+ */
+
+interface BridgeTransportOptions {
+    /** Base URL of the bridge endpoint (no trailing /v1). */
+    endpoint: string;
+    /** API key for Bearer auth. Optional for local bridge servers. */
+    apiKey?: string;
+    /** Request timeout in milliseconds. Default: 30000. */
+    timeout?: number;
+    /** Additional headers to include in every request. */
+    headers?: Record<string, string>;
+    /** Per-request logger. */
+    logger?: Logger;
+}
+declare class BridgeTransport implements Transport {
+    private readonly endpoint;
+    private readonly apiKey?;
+    private readonly timeout;
+    private readonly headers;
+    private readonly logger?;
+    constructor(options: BridgeTransportOptions);
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    request<T>(method: string, params: Record<string, unknown>): Promise<T>;
+    private emit;
+    private buildHeaders;
+}
+
+export { BridgeTransport, type BridgeTransportOptions };

package/dist/testing.js

@@ -0,0 +1,4 @@
+export { BridgeTransport } from './chunk-TGBKROHO.js';
+import './chunk-ASQMU7YC.js';
+//# sourceMappingURL=testing.js.map
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"testing.js"}

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@neo4j-labs/agent-memory",
+  "version": "0.3.0",
+  "description": "Neo4j Labs: TypeScript client for the Neo4j Agent Memory Service (NAMS)",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "Neo4j Labs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neo4j-labs/agent-memory",
+    "directory": "typescript"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./middleware/vercel-ai": {
+      "import": "./dist/middleware/vercel-ai.js",
+      "types": "./dist/middleware/vercel-ai.d.ts"
+    },
+    "./mcp": {
+      "import": "./dist/mcp/index.js",
+      "types": "./dist/mcp/index.d.ts"
+    },
+    "./integrations/langchain": {
+      "import": "./dist/integrations/langchain.js",
+      "types": "./dist/integrations/langchain.d.ts"
+    },
+    "./integrations/mastra": {
+      "import": "./dist/integrations/mastra.js",
+      "types": "./dist/integrations/mastra.d.ts"
+    },
+    "./integrations/strands": {
+      "import": "./dist/integrations/strands.js",
+      "types": "./dist/integrations/strands.d.ts"
+    },
+    "./testing": {
+      "import": "./dist/testing.js",
+      "types": "./dist/testing.d.ts"
+    }
+  },
+  "homepage": "https://neo4j.com/labs/agent-memory/sdks/typescript",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "npm run check:version && tsup",
+    "check:version": "node ./scripts/check-version-sync.mjs",
+    "dev": "tsup --watch",
+    "test": "vitest run test/unit test/integration",
+    "test:unit": "vitest run test/unit",
+    "test:integration": "vitest run test/integration",
+    "test:e2e": "vitest run test/e2e",
+    "test:all": "vitest run",
+    "test:watch": "vitest",
+    "test:tck": "RUN_TCK_BRIDGE=1 vitest run test/tck",
+    "tck:bronze": "RUN_TCK_BRIDGE=1 vitest run test/tck --grep Bronze",
+    "lint": "tsc --noEmit",
+    "docs:api": "typedoc",
+    "conformance:server": "tsx conformance/server.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@ai-sdk/provider": "^3.0.10",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@strands-agents/sdk": "^1.2.0",
+    "@types/node": "^20.0.0",
+    "dotenv": "^17.4.2",
+    "msw": "^2.14.3",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typedoc": "^0.26.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}