Azure Cosmos DB JavaScript SDK<\/strong><\/a> \u2014 the official, promise-based client for Cosmos DB NoSQL, and the piece that does the heavy lifting here. It’s a modern, fully typed TypeScript SDK<\/p>\n We’ll build an agent that authors a Next.js blog and<\/em> keeps a long-term semantic memory in Azure Cosmos DB. Every code sample below is production-shaped, not pseudocode.<\/p>\n If you’ve built with the Vercel AI SDK, eve will feel immediately familiar it\u2019s the same team’s take on agents<\/em>, and its core idea is refreshingly literal: your agent is a folder.<\/strong> There’s no graph DSL to learn and no orchestration boilerplate. You describe the agent with plain files, and eve wires them into a running agent:<\/p>\n <\/p>\n agent.ts<\/strong><\/p>\n What eve deliberately doesn’t<\/em> give you is persistence. A model call is stateless; when the process restarts, the conversation is gone. That’s the gap we fill with Azure Cosmos DB \u2014 turning a stateless agent into one that genuinely remembers<\/strong>.<\/p>\n Agent memory has an awkward shape for traditional databases: you write a lot of small items, you read them back by meaning<\/em> (not exact keys), and you want it fast and global. Azure Cosmos DB NoSQL fits this well:<\/p>\n A CosmosClient owns a connection pool and routing caches. Creating one per request exhausts sockets and adds TLS latency. Create it once<\/strong> and reuse it:<\/p>\n Caching on\u00a0 Pick a partition key that is high-cardinality<\/strong> and immutable<\/strong>, and make the item id equal to it where you can \u2014 then single-item fetches are 1 RU point reads<\/strong> instead of queries:<\/p>\n For lists, use continuation tokens<\/strong>, never OFFSET\/LIMIT:<\/p>\n Here’s where it gets fun. To store embeddings and search them, define a vector embedding policy<\/strong> and a vector index<\/strong> at container-creation time (the policy is immutable afterward):<\/p>\n Storing a memory<\/strong> \u2014 embed the text, then create the item:<\/p>\n Recalling by meaning<\/strong> \u2014 VectorDistance() with ORDER BY, a literal TOP, and a parameterized query vector (so the query plan caches):<\/p>\n Because we filter on the partition key, this stays a single-partition query<\/strong> \u2014 exactly what you want on a hot path.<\/p>\n eve’s model is delightfully simple: every file in `agent\/tools\/` is a tool.<\/strong> You describe its inputs with Zod, and eve hands the model a JSON schema automatically.<\/p>\n Now the agent can decide on its own, to call recall before answering \u2014 and because the memories live in Azure Cosmos DB, they persist across sessions, deploys, and regions.<\/p>\n That’s a complete, durable, semantically searchable memory in well under 200 lines no extra infrastructure, no second database.<\/p>\n The complete, runnable source for everything in this post lives in the AzureCosmosDB\/eve-cosmos-memory repository<\/strong><\/a> clone it and follow along:<\/p>\n Give your agent a memory. The Azure Cosmos DB JavaScript SDK makes the durable,\nglobal, vector-searchable part almost boring which is exactly what you want from\ninfrastructure.<\/p>\n About Azure Cosmos DB<\/strong><\/p>\n Azure Cosmos DB is a fully managed and serverless NoSQL and vector database for modern app development, including AI applications. With its SLA-backed speed and availability as well as instant dynamic scalability, it is ideal for real-time NoSQL and MongoDB applications that require high performance and distributed computing over massive volumes of NoSQL and vector data.<\/p>\n To stay in the loop on Azure Cosmos DB updates, follow us on\u00a0X<\/a>,\u00a0YouTube<\/a>, and\u00a0LinkedIn<\/a>.\u00a0 Join the discussion with other developers on the\u00a0#nosql channel on the Microsoft Open Source Discord<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":" Most “AI agent” demos forget everything the moment the process exits. That’s fine for a toy project, but useless for anything real. An agent that helps you write, triage, or support needs two things a language model alone can’t give it: durable state and the ability to recall the right context by meaning. This post […]<\/p>\n","protected":false},"author":80443,"featured_media":12689,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1610,1980],"tags":[2030,1864,2029,1859,1872,2027],"class_list":["post-12685","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-ai","category-azure-cosmos-db","tag-agentmemory","tag-azurecosmosdb","tag-eve","tag-javascript","tag-nosql","tag-semantic-search"],"acf":[],"blog_post_summary":" Most “AI agent” demos forget everything the moment the process exits. That’s fine for a toy project, but useless for anything real. An agent that helps you write, triage, or support needs two things a language model alone can’t give it: durable state and the ability to recall the right context by meaning. This post […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/12685","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/users\/80443"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/comments?post=12685"}],"version-history":[{"count":2,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/12685\/revisions"}],"predecessor-version":[{"id":12693,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/12685\/revisions\/12693"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media\/12689"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media?parent=12685"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/categories?post=12685"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/tags?post=12685"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}![\"Diagram](\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/07\/context.png\")
<\/a><\/p>\nMeet eve: agents as a filesystem<\/h2>\n
![\"Diagram](\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/07\/Image.png\")
<\/a><\/p>\n\n
import { createAzure } from \"@ai-sdk\/azure\";\r\nimport { defineAgent } from \"eve\";\r\n \r\nconst azure = createAzure({\r\n baseURL: `${process.env.AZURE_OPENAI_ENDPOINT}\/openai`,\r\n apiKey: process.env.AZURE_OPENAI_API_KEY,\r\n apiVersion: \"preview\",\r\n});\r\n \r\nexport default defineAgent({\r\n model: azure.chat(\"gpt-4.1\"), \/\/ your Azure deployment name\r\n});\r\n<\/code><\/pre>\n\n
Why Azure Cosmos DB for agent memory?<\/h2>\n
\n
Step 1: A singleton client (the #1 SDK rule)<\/h2>\n
\/\/ src\/lib\/cosmos.ts \r\n import { CosmosClient } from \"@azure\/cosmos\"; \r\n import { DefaultAzureCredential } from \"@azure\/identity\"; \r\n \r\n type CosmosGlobal = typeof globalThis & { __client?: CosmosClient }; \r\n \r\n export function getCosmosClient(): CosmosClient { \r\n const g = globalThis as CosmosGlobal; \r\n if (!g.__client) { \r\n g.__client = new CosmosClient({ \r\n endpoint: process.env.COSMOS_ENDPOINT!, \r\n \/\/ Prefer Entra ID over keys. Falls back to a key only if provided. \r\n aadCredentials: new DefaultAzureCredential(), \r\n connectionPolicy: { \r\n \/\/ Let the SDK absorb transient 429s with backoff. \r\n retryOptions: { maxRetryAttemptCount: 9, maxWaitTimeInSeconds: 30 }, \r\n }, \r\n }); \r\n } \r\n return g.__client; \r\n } \r\n<\/code><\/pre>\nglobalThis\u00a0<\/code>matters in dev: frameworks like Next.js reset module state on hot-reload, which would otherwise leak a new client on every save.<\/p>\nStep 2: Model for cheap reads<\/h2>\n
\/\/ A blog post: id === slug, partition key is \/slug. \r\n const { resource: post } = await container \r\n .item(slug, slug) \/\/ (id, partitionKey) \r\n .read(); \/\/ ~1 RU, single-digit ms \r\n<\/code><\/pre>\n const iterator = container.items \r\n .query({ query: \"SELECT c.slug, c.title FROM c WHERE c.status = 'published'\" }) \r\n .getAsyncIterator(); \r\n \/\/ ...or .query(spec).fetchNext() and pass resource.continuationToken to the client. \r\n<\/code><\/pre>\nStep 3: Turn the container into a vector memory store<\/h2>\n
\r\n import { \r\n VectorEmbeddingDataType, \r\n VectorEmbeddingDistanceFunction, \r\n VectorIndexType, \r\n } from \"@azure\/cosmos\"; \r\n \r\n await database.containers.createIfNotExists({ \r\n id: \"memory\", \r\n partitionKey: { paths: [\"\/sessionId\"] }, \/\/ one conversation per partition \r\n defaultTtl: -1, \/\/ TTL enabled; set per-item `ttl` for ephemeral memories \r\n vectorEmbeddingPolicy: { \r\n vectorEmbeddings: [ \r\n { \r\n path: \"\/embedding\", \r\n dataType: VectorEmbeddingDataType.Float32, \r\n dimensions: 1536, \/\/ text-embedding-3-small \r\n distanceFunction: VectorEmbeddingDistanceFunction.Cosine, \r\n }, \r\n ], \r\n }, \r\n indexingPolicy: { \r\n includedPaths: [{ path: \"\/*\" }], \r\n \/\/ CRITICAL: keep the raw vector out of the regular index (saves write RUs). \r\n excludedPaths: [{ path: \"\/embedding\/*\" }], \r\n vectorIndexes: [{ path: \"\/embedding\", type: VectorIndexType.QuantizedFlat }], \r\n }, \r\n<\/code><\/pre>\n import { randomUUID } from \"node:crypto\"; \r\n async function appendMemory(sessionId: string, content: string) { \r\n const embedding = await embedText(content); \/\/ Azure OpenAI embeddings \u2192 number[] \r\n await container.items.create({ \r\n id: randomUUID(), \r\n sessionId, \r\n type: \"memory\", \r\n content, \r\n embedding, \r\n createdAt: new Date().toISOString(), \r\n }); \r\n } \r\n<\/code><\/pre>\n async function recall(sessionId: string, query: string, k = 5) { \r\n const vector = await embedText(query); \r\n const { resources } = await container.items \r\n .query( \r\n { \r\n query: \r\n `SELECT TOP ${k} c.content, VectorDistance(c.embedding, @vec) AS score ` + \r\n `FROM c WHERE c.type = \"memory\" AND c.sessionId = @sessionId ` + \r\n `ORDER BY VectorDistance(c.embedding, @vec)`, \r\n parameters: [ \r\n { name: \"@vec\", value: vector }, \r\n { name: \"@sessionId\", value: sessionId }, \r\n ], \r\n }, \r\n { partitionKey: sessionId }, \/\/ single-partition \u2192 cheap and fast \r\n ) \r\n .fetchAll(); \r\n return resources; \/\/ nearest memories, most similar first \r\n } \r\n<\/code><\/pre>\nStep 4: Expose it to the agent as an eve tool<\/h2>\n
\r\n \/\/ agent\/tools\/recall.ts \r\n import { defineTool } from \"eve\/tools\"; \r\n import { z } from \"zod\"; \r\n import { blogApiUrl, authHeaders } from \"..\/lib\/blog-client.js\"; \r\n \r\n export default defineTool({ \r\n description: \r\n \"Recall the most relevant saved memories for a query using vector search.\", \r\n inputSchema: z.object({ \r\n query: z.string().min(1).describe(\"What to search your memory for.\"), \r\n sessionId: z.string().optional(), \r\n k: z.number().int().min(1).max(20).default(5), \r\n }), \r\n async execute({ query, sessionId, k }) { \r\n const url = new URL(blogApiUrl(\"\/api\/memory\")); \/\/ resolves BLOG_API_URL \r\n url.searchParams.set(\"q\", query); \r\n url.searchParams.set(\"k\", String(k)); \r\n if (sessionId) url.searchParams.set(\"sessionId\", sessionId); \r\n const res = await fetch(url, { headers: authHeaders() }); \r\n const { results } = await res.json(); \r\n return { ok: true, memories: results }; \r\n }, \r\n<\/code><\/pre>\nThe full loop<\/h2>\n
![\"Diagram](\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/07\/full-loop.png\")
<\/a><\/p>\nTry it<\/h2>\n
npm install \r\n npm run seed # creates the DB, blog container, and vector memory container \r\n npm run dev # the blog (Next.js on Vercel) \r\n npm run agent # chat with the eve agent \u2014 ask it to remember and recall \r\n<\/code><\/pre>\n