Bolt and NAMS backends

Choose Bolt when you operate Neo4j, need custom write Cypher, want to configure local extraction/embedding providers and drive them from your own ontology, or use preferences, facts, graph adoption, geospatial queries, buffering, or consolidation. Database access, backups, indexes and upgrades remain your responsibility. An air-gapped deployment also needs locally available models and dependencies; selecting Bolt alone does not disable outbound provider requests.

Choose NAMS when a managed workspace and REST API suit the application. The service manages the storage and extraction pipeline. Applications use supported conversation, entity, graph, reasoning and ontology operations; they do not gain every Bolt method by changing the connection settings. The TypeScript SDK’s normal transport is NAMS REST.

One client has one backend. An application can create separate clients for separate stores, but moving data, reconciling identifiers and authorizing access are application responsibilities.

The canonical backend capabilities reference lists language, operation, return-shape and scope differences. A method can satisfy a Python protocol or appear in a TypeScript compatibility interface while raising NotSupportedError on the selected backend. A Bolt-only Python method can also be absent from the NAMS store, so calling it raises AttributeError, and some Bolt options are silently dropped. Interface similarity is useful for adapters; it is not proof of behavioral portability.

Preferences, facts, client-created relationships and extraction-pipeline configuration are Bolt capabilities. Hosted applications can retrieve information from messages and extracted entities instead, but should not describe that as an equivalent preference/fact API. The hosted Cypher endpoint is read-only.

Ontology management is the exception that runs on both. Since 0.7.0, client.ontology on Bolt stores versioned ontologies as :Ontology / :OntologyVersion nodes in your database, and the document the client resolves at connect time drives local extraction, relation validation and entity resolution; client.ontology_document and client.validation_mode report it. On NAMS the same methods manage the workspace’s ontology, which governs server-side extraction. The mechanics differ: a Bolt client converts imports locally, runs migrate synchronously, and picks up a newly activated version at its next connection. See Bolt and NAMS mechanics.

NAMS uses a workspace as the tenancy boundary, selected by the authenticated key or the supported workspace header. Conversation user identifiers are separate metadata and filtering inputs. Reusing a user identifier does not automatically load an earlier conversation.

Bolt’s user nodes and selected user_identifier arguments associate data with a user. They do not provide universal authorization or add user filters to all searches. In particular, the current Bolt semantic message search accepts session_id but does not apply it to its Cypher query. Applications must review their retrieval paths and database access boundaries; see data scope and scoped reads and writes.

The Bolt client opens a driver connection pool and issues Cypher. Client-side providers can generate embeddings and extracted entities, while Neo4j stores memory and indexes. The chosen provider determines whether model processing is local or remote. Extraction and, since 0.7.0, resolution of the extracted mentions against stored entities run in the client within the add_message call, so there is no separate extraction-readiness state to wait for.

A NAMS client calls the service over HTTPS. Writes and background extraction have different completion points: a stored message can be readable before its extracted graph is ready. A workflow that needs extracted entities must use the supported readiness/status APIs with bounded waiting.

The hosted API uses REST /v1. A TCK bridge exists for development and conformance testing; it is not an alternative hosted feature surface. Conformance labels describe clients, not paid service tiers.

Backend-specific failures and retry behavior belong to each SDK’s reference: Python and TypeScript. Do not copy one language’s error class or retry promise into the other language’s guide.

Migration requires reviewing supported operations, returned IDs, result shapes, extraction readiness and data scope. See Migrate to NAMS for the task and Use NAMS for connection setup.

Latency depends on network placement, request size, index state, graph size and model processing. A local database can avoid a hosted network hop; a managed service removes database operations work. Batch supported writes to reduce per-request overhead and measure the complete workload before choosing limits or deployment topology. No universal millisecond or throughput comparison is established here.