Vercel AI SDK — NAMS Chat with Neo4j Agent Memory

git clone https://github.com/neo4j-labs/neo4j-agent-integrations.git
cd neo4j-agent-integrations/vercel-agent/vercel_Nams_demo

npm install                       # no flags needed — strict peer resolution passes

cp .env.local.example .env.local  # set MEMORY_API_KEY and OPENAI_API_KEY at minimum

npm run dev                       # http://localhost:3000

NAMS_MODE=provider     # (default) transparent memory, wraps a provider
NAMS_MODE=middleware   # transparent memory, wraps a model instance
NAMS_MODE=tools        # model calls query_memory / store_memory explicitly

┌───────────────────────────────────────────────────────────────────┐
│  Browser (Next.js / React)                                        │
│                                                                   │
│  ChatComponent (useChat + DefaultChatTransport)                   │
│    • sessionId from localStorage (key: nams-session-id)           │
│    • POST /api/chat  { messages, sessionId, conversationId? }     │
│    • GET  /api/reasoning?userId=&conversationId=                  │
│                                                                   │
│  ┌──────────────────────┐  ┌──────────────────────────────────┐   │
│  │  Memory Panel        │  │  Reasoning Trace Panel           │   │
│  │  recent / observ. /  │  │  step 1 → step 2 → … → step N    │   │
│  │  reasoning tabs      │  │  reasoning / action / result     │   │
│  └──────────────────────┘  └──────────────────────────────────┘   │
└───────────────────────┬───────────────────────────────────────────┘
                        │  HTTP streaming (UI message stream)
                        ▼
┌────────────────────────────────────────────────────────────────────┐
│  Next.js API Routes (Node.js runtime)                              │
│                                                                    │
│  POST /api/chat                      GET /api/reasoning            │
│  ───────────────────────────────     ─────────────────────────     │
│  1. Parse UIMessages + sessionId     1. findExistingConversation   │
│  2. Resolve model by NAMS_MODE       2. client.reasoning.listSteps │
│  3. Connect MCP (mode-dependent)     3. Return step array as JSON  │
│  4. Build DATABASE ACCESS prompt        (no conversation → [])     │
│  5. ToolLoopAgent streams response                                 │
│  6. onFinish → recordStep → close()                                │
│                                                                    │
└───────────────────────┬────────────────────────────────────────────┘
                        │  HTTPS REST
                        ▼
┌────────────────────────────────────────────────────────────────────┐
│  NAMS  —  https://memory.neo4jlabs.com                             │
│  (@neo4j-labs/agent-memory SDK, backed by Neo4j AuraDB)            │
│                                                                    │
│  ┌──────────────────┐  ┌───────────────────┐  ┌────────────────┐   │
│  │  Short-Term      │  │  Long-Term        │  │  Reasoning     │   │
│  │  (conversation)  │  │  (graph entities) │  │  (step records)│   │
│  │  • search        │  │  • facts          │  │  • reasoning   │   │
│  │  • per convId    │  │  • user_pref      │  │  • actionTaken │   │
│  │  • cross-session │  │  • patterns       │  │  • result      │   │
│  └──────────────────┘  └───────────────────┘  └────────────────┘   │
└────────────────────────────────────────────────────────────────────┘

vercel_Nams_demo/
│
├── app/
│   ├── api/
│   │   ├── chat/route.ts          ← POST /api/chat — mode switching, ToolLoopAgent
│   │   └── reasoning/route.ts     ← GET  /api/reasoning — fetch stored reasoning steps
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx                   ← dark/light shell + AppHeader + ChatComponent
│
├── components/
│   ├── AppHeader.tsx
│   └── chat/
│       ├── ChatComponent.tsx      ← useChat, streaming, session id, reasoning fetch
│       ├── MemoryPanel.tsx        ← retrieved memories (recent / observations / reasoning)
│       ├── ReasoningPanel.tsx     ← per-step reasoning trace
│       └── styles.ts
│
├── lib/
│   ├── constants.ts               ← SYSTEM_PROMPT + buildDbToolsPrompt()
│   ├── nams-enrich.ts             ← ensureStored() — persists a turn the model didn't store
│   └── neo4j-mcp.ts               ← MCP client, auth resolution, explainMcpError()
│
├── test/
│   ├── chat-route.test.ts         ← mode wiring + error paths for /api/chat
│   └── reasoning-route.test.ts    ← trace lookup + error paths for /api/reasoning
│
├── types/index.ts                 ← MemoryHit, QueryOutput, ReasoningStep, ParsedMemory
├── utils/message.ts               ← getMsgText, parseMemory, formatErrorMessage
├── constants.ts                   ← DEFAULT_SUGGESTIONS, SESSION_STORAGE_KEY
├── declarations.d.ts              ← `declare module '*.css'`
├── .env.local.example
├── package.json
├── vitest.config.mts
└── next.config.js

Send: "My name is Alex and I like TypeScript"
→ Memory + Reasoning panels appear above the answer
→ Reasoning trace: query_memory → answer → store_memory
→ Send: "What language do I like?"
→ query_memory returns found=true; the model answers from memory

Send: "What nodes are in my Neo4j database?"
→ [chat] model=gpt-5.4-mini  maxSteps=10  tools=5  db=[get_neo4j_schema, read_neo4j_cypher, write_neo4j_cypher]
→ Agent calls the schema tool, then the read tool, then offers to store findings

Send: "My favourite colour is blue"
→ No query_memory / store_memory in the logs — memory is middleware-driven
→ Refresh the page (same localStorage session id); send: "What's my favourite colour?"
→ Model answers "blue" — retrieved before the model call

npm install @neo4j-labs/nams-ai-provider @neo4j-labs/agent-memory ai zod

import { createNamsProvider, createNams } from '@neo4j-labs/nams-ai-provider';
import { openai } from '@ai-sdk/openai';

// Provider mode — transparent
const model = createNamsProvider({ apiKey, baseProvider: openai, scope: { userId } })
  .languageModel('gpt-5.4-mini');

// Middleware mode — transparent, wraps an existing model
const wrapped = createNams({ apiKey }).wrap(openai('gpt-5.4-mini'), { userId });

// Tools mode — model-driven, tool calls visible in the UI
const { tools, close } = await createNams({ apiKey }).toolsWithMcp({ userId });