Files
Bundle OKF 0.1 · 9 conceitos · johnymontana/agentic-commerce-ontology-neo4j
Open source Repository Open in the app JSON README (API)
About
# Files
- [Agentic Commerce Ontology wiki](quickstart.md) - A task-oriented guide to the Next.js hardware-store demo, its Neo4j commerce graph, Eve agent, NAMS memory integration, and operations.
# Directories
- [agent](agent/)
- [architecture](architecture/)
- [commerce](commerce/)
- [graph](graph/)
- [operations](operations/)
- [provider](provider/)
- [security](security/)
- [storefront](storefront/)
Details
- Kind
- OKF bundles
- Topic
- AI, RAG & memory
- Publisher
- johnymontana
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Last push
- 2026-08-16T17:18:42Z
- Repository state
- ativo
- Language
- TypeScript
- Added
- 2026-09-08 09:04:14
- Updated
- 2026-09-08 09:04:14
- Origin id
johnymontana/agentic-commerce-ontology-neo4j:openwiki/index.md
README
# Agentic Commerce Ontology
A reference hardware-store application showing how a commerce knowledge graph can be both the transactional system of record and the grounding layer for a durable shopping agent.
The demo combines:
- **Neo4j** for customers, authentication sessions, catalog, variants, compatibility, projects, store offers, inventory, carts, and orders.
- **Neo4j Agent Memory Service (NAMS)** for conversation, preference, and action memory scoped to the signed-in customer.
- **Next.js 16** for the storefront and server routes.
- **Vercel Eve** for durable agent sessions, authentication-aware tools, approvals, and event hooks.
- **Vercel AI SDK 7** and **Vercel AI Gateway** for model access and streaming.
- A vendored **NAMS Vercel AI SDK provider** that retrieves relevant NAMS context before each model step.
The result is not just a chatbot beside a catalog. Scout, the demo assistant, can traverse project requirements, SKU interfaces, substitutions, live store offers, and inventory; assemble a project kit; remember a stable preference; modify the authenticated customer's cart; and place a pickup order only after approval and a transactional stock recheck.
> **Data-boundary note:** all canonical application and commerce-domain data is stored in Neo4j. NAMS memory is also graph-backed. Eve necessarily keeps its own durable operational state—agent runs, workflow events, continuations, and approvals—in the Eve runtime. That operational state is not presented as commerce data and is not duplicated as the system of record in the application graph. `AgentSession` and `AgentEvent` nodes in Neo4j are ownership/idempotency bridge records, not a replacement for Eve's runtime store.
## Deliverables
- The full-stack reference application in `app`, `components`, `lib`, and `agent`.
- The detailed [architecture reference](docs/architecture.md).
- The implemented [commerce ontology and Cypher invariants](docs/ontology.md).
- The presentation deck: [Agentic Commerce Ontology](docs/agentic-commerce-ontology.pptx).
- The reproducible presentation source: [`scripts/build-presentation.mjs`](scripts/build-presentation.mjs).
- Offline security/ontology tests in `tests` and the safe NAMS connectivity probe in `scripts/verify-nams.ts`.
## What the demo proves
- A graph can answer connected shopping questions that are awkward as independent keyword searches: “What complete kit satisfies this project, fits these interfaces, is in stock here, and respects what I already own?”
- The same relationship model grounds storefront pages and agent tools, so there is one source of truth for recommendations and transactions.
- An authenticated user—not an LLM-supplied `userId`—owns carts, orders, agent sessions, and NAMS scope.
- NAMS can restore useful context across separate Eve sessions without placing raw conversation history in browser storage.
- Checkout can remain deterministic and transactional even when the discovery journey is conversational.
- Recommendations can expose graph evidence: requirement satisfaction, shared interface standards, alternatives, store availability, aisle, and bin.
## Architecture
```mermaid
flowchart LR
Browser["Next.js storefront\nand Eve chat UI"]
Routes["Next.js server routes\nauth + cart + checkout"]
Eve["Vercel Eve runtime\nsessions + tools + approvals"]
Provider["NAMS AI SDK 7 provider\ncontext retrieval"]
Gateway["Vercel AI Gateway\nmodel routing"]
Neo4j[("Neo4j\ncommerce system of record")]
NAMS["Neo4j Agent Memory Service\nshort-term + long-term + action memory"]
MemoryGraph[("Neo4j-backed\nmemory graph")]
Browser --> Routes
Browser --> Eve
Routes --> Neo4j
Eve -->|"authenticated tools"| Neo4j
Eve --> Provider
Provider --> NAMS
Provider --> Gateway
NAMS --> MemoryGraph
Eve -->|"event hooks; idempotent bridge"| NAMS
Eve -->|"session ownership + event claims"| Neo4j
```
The target reference deployment can place the NAMS memory graph and the commerce subgraph in the same Neo4j deployment. A hosted NAMS workspace may instead use a service-managed Neo4j database; in that mode the system uses two Neo4j deployments, while the application/domain system of record remains the configured application Neo4j database. See [Architecture](docs/architecture.md) and [Ontology](docs/ontology.md) for the full data and trust model.
## Prerequisites
- **Node.js 24 or newer.** Eve `0.30.x` requires Node 24+.
- **pnpm 10** (`corepack enable` is usually sufficient).
- **Docker** with Compose for the local Neo4j quickstart, or a reachable Neo4j 5.x/AuraDB instance.
- For agent responses: a **Vercel AI Gateway** credential locally, or Vercel OIDC in a Vercel deployment.
- For durable memory: a **NAMS API key and workspace id** from [Neo4j Agent Memory](https://neo4j.com/labs/agent-memory/).
The catalog, project explorer, authentication, cart, and order flows can run without NAMS. The assistant can run without memory when model access is configured. The full cross-session-memory demo requires both NAMS and model access.
## Quickstart
1. Install dependencies and create local configuration.
```bash
corepack enable
pnpm install
cp .env.example .env.local
```
2. Start Neo4j, apply constraints/indexes, and seed the hardware-store graph.
```bash
docker compose up -d
pnpm db:setup
```
Neo4j Browser is available at [http://localhost:7474](http://localhost:7474). The compose credentials match `.env.example` (`neo4j` / `agentic-commerce`).
3. Start the application.
```bash
pnpm dev
```
4. Open [http://localhost:3000](http://localhost:3000) and sign in with one of the demo customers below.
To explore only the storefront while configuring Eve, set `DISABLE_EVE=1` in `.env.local` and restart the dev server.
## Demo customers
| Customer | Email | Password | Seeded context |
| --- | --- | --- | --- |
| Avery Builder | `avery@example.com` | `buildbetter` | Intermediate, store pickup, plumbing/faucet interests |
| Jordan Fixer | `jordan@example.com` | `fixitfast` | Beginner, delivery preference, shelving/drywall interests |
These credentials are public test data. Never deploy them as real accounts.
## Configuration
Copy `.env.example` to `.env.local` and set the values appropriate to the deployment.
| Variable | Required | Default/purpose |
| --- | --- | --- |
| `NEO4J_URI` | yes | `bolt://localhost:7687`; application graph endpoint |
| `NEO4J_USERNAME` | yes | `neo4j` |
| `NEO4J_PASSWORD` | yes | No code default; compose uses `agentic-commerce` |
| `NEO4J_DATABASE` | no | `neo4j` |
| `MEMORY_API_KEY` | full demo | NAMS credential; blank disables NAMS calls |
| `MEMORY_WORKSPACE_ID` | full demo | NAMS workspace; blank disables NAMS calls |
| `MEMORY_API_ENDPOINT` | no | `https://memory.neo4jlabs.com/v1` |
| `AI_GATEWAY_API_KEY` | local agent | Vercel AI Gateway key; Vercel deployments can use OIDC |
| `AGENT_MODEL` | no | `openai/gpt-5.4-mini` |
| `SESSION_COOKIE_NAME` | no | `aco_session` |
| `SESSION_TTL_DAYS` | no | `7` |
| `DISABLE_EVE` | no | Set to `1` for storefront-only development |
`DEMO_AUTH_ENABLED` is documented in the example environment for an eventual production/demo switch, but the current reference login routes should be considered demo-only regardless of its value.
### NAMS and AI Gateway hosted mode
1. Create a NAMS workspace and API key at [memory.neo4jlabs.com](https://memory.neo4jlabs.com).
2. Set `MEMORY_API_KEY` and `MEMORY_WORKSPACE_ID`. Keep the NAMS endpoint at its hosted default unless using another NAMS deployment.
3. For the literal one-Neo4j reference topology, configure NAMS/self-managed memory to use the same Neo4j deployment as the application. If the hosted workspace is service-managed, document that the memory graph is a second Neo4j deployment.
4. Create a Vercel AI Gateway key for local development and set `AI_GATEWAY_API_KEY`. On Vercel, follow the [AI Gateway authentication documentation](https://vercel.com/docs/ai-gateway/authentication) for OIDC or key-based authentication.
5. Run the safe connectivity/isolation probe:
```bash
pnpm nams:verify
```
The probe prints no secret values, creates two random temporary users/conversations, verifies user-filtered listings and message separation, and deletes both conversations. With NAMS variables absent it exits successfully with a clear skip.
## Why the provider is vendored
The npm release of `@neo4j-labs/nams-ai-provider` available when this reference was built targets the older Vercel AI SDK provider contract. Eve `0.30.7` uses AI SDK 7 / `LanguageModelV4`, so this repository vendors the upstream provider source that implements that contract:
- Upstream repository: [`neo4j-labs/agent-memory`](https://github.com/neo4j-labs/agent-memory)
- Upstream package path: `typescript/packages/vercel-ai-provider`
- Version: `0.2.0`
- Commit: [`ac86a8ff01354e6b9c4d1b17089fba89d42dcf2b`](https://github.com/neo4j-labs/agent-memory/commit/ac86a8ff01354e6b9c4d1b17089fba89d42dcf2b)
- Local workspace package: `packages/nams-ai-provider`
The local copy adds a narrowly scoped `namespace` option passed to `MemoryClient`, so the namespace is derived from the authenticated customer instead of model input. It also includes explicit public return annotations needed for portable declaration generation in this pnpm workspace. Review and replace the vendored package when an equivalent AI SDK 7-compatible release is published.
The agent configures the provider with `persistInteractions: false`. Context retrieval still occurs through the provider, while Eve hooks make one deduplicated persistence attempt using durable Eve event ids claimed in Neo4j. This avoids duplicate NAMS writes when an Eve event is replayed or a provider wrapper is reconstructed on a serverless step. Because the claim precedes the NAMS call, a failed write is not retried by the current demo; production code should add `PENDING`/`COMPLETED` claim state and a retry worker if at-least-once delivery is required.
## Useful commands
| Command | Purpose |
| --- | --- |
| `pnpm dev` | Run Next.js with Eve integration |
| `DISABLE_EVE=1 pnpm dev` | Run the storefront without the Eve runtime |
| `pnpm build` | Build the vendored provider and production app |
| `pnpm typecheck` | Type-check the workspace |
| `pnpm lint` | Run ESLint |
| `pnpm test` | Run offline Vitest checks |
| `pnpm db:migrate` | Apply Neo4j constraints and indexes idempotently |
| `pnpm db:seed` | Seed/update demo data idempotently |
| `pnpm db:setup` | Migrate, then seed |
| `pnpm nams:verify` | Probe NAMS connectivity and user scoping safely |
| `pnpm nams-provider:build` | Rebuild the vendored AI SDK 7 provider |
| `pnpm agent:info` | Inspect Eve's discovered project configuration |
Health is exposed at `GET /api/health`. It verifies Neo4j connectivity and reports whether NAMS variables are configured; it deliberately does not disclose credentials or call NAMS.
## User isolation and security model
Identity is established at the server boundary and propagated inward:
1. The login route normalizes email, verifies a salted `scrypt` password hash, creates a random 256-bit opaque token, and stores only its SHA-256 hash in an `AuthSession` node.
2. The browser receives the token in an `HttpOnly`, `SameSite=Lax` cookie (`Secure` in production).
3. State-changing Next.js routes reject a mismatched `Origin`/`Host` and derive the customer from that cookie.
4. Eve authentication derives `principalId` from the same server-side session. Agent tool schemas never accept `customerId`.
5. Every cart/order query anchors at `(:Customer {id: $customerId})`.
6. Eve session resumes are checked against `(Customer)-[:HAS_AGENT_SESSION]->(AgentSession)` ownership.
7. NAMS clients and the provider receive `namespace: agentic-commerce:<customerId>` and `scope.userId` from the authenticated principal.
8. Eve hook writes use a unique `AgentEvent.eventId` claim so replayed events do not write memory twice.
The NAMS verification script validates API user filtering and data separation, not a hostile-tenant authorization boundary. Production multi-tenancy should use the isolation primitive guaranteed by the chosen NAMS deployment (dedicated workspace/database, supported tenant namespace, or equivalent), test direct-object-access behavior, rotate credentials, and add centralized policy/audit controls.
This login is intentionally simple. It does **not** include registration, email verification, password reset, MFA, breached-password checks, rate limiting, session rotation, device management, or an external identity provider. The `localDev()` Eve authenticator is useful locally and becomes a no-op in production, but local environments should still be treated as trusted developer machines.
## Suggested live demo
1. Sign in as **Avery** and open “Replace a bathroom faucet.” Show that project steps, requirements, compatible SKU options, price, aisle, and stock all come from traversing Neo4j.
2. Ask Scout: “I have a basin wrench and prefer brushed brass. Build the rest of the faucet kit for store pickup.” Let the assistant save stable preferences, omit the owned tool, check both connector interfaces, and assemble a cart.
3. Ask why the `1/2-inch FIP × 1/2-inch FIP` lookalike line is wrong for the seeded angle stop. Show the explicit `INCOMPATIBLE_WITH` reason and interface standards (`WATER_1_2_FIP` vs `WATER_3_8_COMPRESSION`).
4. Approve pickup checkout. Explain that the order transaction re-reads offer prices and inventory, increments `reserved`, snapshots order-line prices, and changes the cart to `ORDERED` atomically.
5. Start a fresh agent session as Avery and ask, “Which finish do I prefer, and what tool do I already own?” Show cross-session memory.
6. Sign out and sign in as **Jordan**. Ask the same question and show that Avery's conversation and preferences are absent while Jordan's graph-owned cart/order data is independent.
7. Open Neo4j Browser and run one of the invariant queries in [docs/ontology.md](docs/ontology.md) to make the grounding path visible.
## Current scope and limitations
- This is a reference implementation, not a PCI-ready store. Checkout creates a pickup reservation; it does not charge a payment method, calculate tax, ship, refund, or integrate with an ERP/PIM/OMS.
- Inventory locking is demonstrated through one Neo4j write transaction. A production implementation should add reservation expiry, fulfillment state transitions, contention/load testing, and operational recovery.
- Catalog search is deliberately simple (`CONTAINS`) even though a full-text index is created. Production ranking would combine full-text/vector recall with graph constraints and merchandising rules.
- The compatibility graph is illustrative, not a substitute for manufacturer instructions, safety review, building codes, or professional advice.
- The demo has a single store and USD pricing. The ontology supports extending offers and inventory per store.
- NAMS is a **Neo4j Labs, experimental, community-supported** project with no SLA or backward-compatibility guarantee. See the [NAMS project status](https://neo4j.com/labs/agent-memory/).
- Eve is an evolving open framework. Pin its version, review release notes, and test upgrades against session/auth/tool semantics. See the [Vercel Eve repository](https://github.com/vercel/eve).
- The vendored provider is a compatibility bridge and should be tracked as third-party source, not treated as a permanent fork.
- Memory is useful context, not authority. Prices, availability, compatibility, carts, and orders are always re-read from the canonical graph through tools.
## Primary references
- [Neo4j Agent Memory overview](https://neo4j.com/labs/agent-memory/)
- [NAMS TypeScript + Vercel AI SDK integration](https://neo4j.com/labs/agent-memory/how-to/typescript/vercel-ai/)
- [Neo4j Agent Memory source](https://github.com/neo4j-labs/agent-memory)
- [Neo4j JavaScript Driver Manual](https://neo4j.com/docs/javascript-manual/current/)
- [Cypher Manual](https://neo4j.com/docs/cypher-manual/current/)
- [Vercel Eve](https://vercel.com/eve) and [source repository](https://github.com/vercel/eve)
- [Vercel AI SDK](https://ai-sdk.dev/docs/introduction)
- [Vercel AI Gateway](https://vercel.com/docs/ai-gateway)
## License and status
The application is a demo/reference implementation. The vendored NAMS provider retains its upstream license and provenance in `packages/nams-ai-provider`.